Skip to content

Rewrite the COLOR property docstring in Pythonic style - #2160

Open
sneha-shukla-dev wants to merge 1 commit into
PyCalendar:mainfrom
sneha-shukla-dev:docs/1244-color-property-docstring
Open

sneha-shukla-dev wants to merge 1 commit into
PyCalendar:mainfrom
sneha-shukla-dev:docs/1244-color-property-docstring

Conversation

@sneha-shukla-dev

Copy link
Copy Markdown

Linked issue

Description

This replaces the RFC copy-paste in the shared color_property docstring, which is used by Event.color, Journal.color, and Todo.color. The previous text used RFC section headings (Property Parameters, Conformance, Description) that the docstring style check rejects. The new docstring has a short summary, notes that this is COLOR from RFC 7986 section 5.9, links the three component attributes, includes a doctest that prints the decoded iCalendar form and reads the value back, and points to Calendar.color for the calendar-level property (including the X-APPLE-CALENDAR-COLOR alias).

I did not change Calendar.color, which already has a rewritten docstring, and I did not touch Alarm trigger properties, which are covered by open pull request #2094.

Open pull requests #1835 and #1967 also edit src/icalendar/attr/__init__.py, but they change other functions, not color_property. See #1835 and #1967.

Open pull request #2153 also edits that file to mark private helpers with :meta private:, not color_property. See #2153.

I used an AI assistant (Grok Bot) to help identify an unchecked #1244 item that was not already covered by an open pull request, draft the rewritten docstring from the style guide and nearby examples such as categories_property and Calendar.color, and prepare the changelog entry and this pull request description.

Checklist

  • I added a change log entry, following the instructions in all subsections under Change log requirements.
  • I followed icalendar's Artificial intelligence policy and disclosed my Responsible AI use in my commit messages, if applicable.
  • I added or updated tests, if applicable.
  • I ran and ensured all tests pass locally by following Run tests.
  • I added or edited documentation as necessary, both as docstrings to be rendered in the API documentation and narrative documentation, following the Style guide.

Additional information

I did not add new tests; the rewritten example is exercised by the existing doctest suite. I ran ruff format --check and ruff check on src/icalendar/attr/__init__.py, pytest src/icalendar/tests/test_with_doctest.py -k "icalendar.attr" (2 passed), pytest src/icalendar/tests/test_docstrings.py (1877 passed, 563 xfailed), pytest -k color excluding fuzz tests (54 passed), and sphinx-build -W -b html (build succeeded; the new wording appears on the Event, Journal, and Todo API pages). I did not run the full tox matrix.

The changelog fragment is news/1244.documentation.3.

The shared color_property docstring still used RFC section headings
(Property Parameters, Conformance, Description). Replace them with a
summary, implementation notes, cross-references to Event.color,
Journal.color, and Todo.color, a doctest example, and a pointer to
Calendar.color.

AI disclosure:
I used an AI assistant (Grok Bot) to help pick one unchecked PyCalendar#1244
item not already covered by an open pull request, compare the old
docstring with the categories_property and Calendar.color examples,
rewrite it to the project style guide, and prepare the changelog
entry.
Prompts summarized: list remaining RFC-style docstrings for issue
PyCalendar#1244; avoid Alarm trigger items already in PR PyCalendar#2094; rewrite
color_property; add news/1244.documentation.3 with the required AI
disclosure.
Output: this commit.
@github-actions github-actions Bot added the ai-suspicion This contribution is possibly created with lots of AI help without enough human understanding. label Nov 19, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Thanks for the pull request, @sneha-shukla-dev! A maintainer will review it shortly.

@github-actions

Copy link
Copy Markdown
Contributor

One or more PR-quality checks did not pass. Review the PR Quality Checks summary in the workflow run for the failed checks and their details, then make any necessary updates.

Checklist items may remain unchecked while work is in progress. Please tick each item as you complete it.

If you used AI assistance, follow the project's Responsible AI use policy and provide the required disclosures.

@github-actions

Copy link
Copy Markdown
Contributor

Insufficient data

Not enough activity yet to make a reliable assessment.

View full analysis →

Evidence
  • Recently created: Account is 0 days old

This is an automated analysis by AgentScan

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ai-suspicion This contribution is possibly created with lots of AI help without enough human understanding.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant