Skip to content

Navigation Menu

Sign in
Sign up

Fix broken doc links in Calendar.new docstring - #1732

Open
Mohammed-Ahmed7 wants to merge 1 commit into
collective:main from
Mohammed-Ahmed7:fix/calendar-doc-links
Open

Fix broken doc links in Calendar.new docstring #1732
Mohammed-Ahmed7 wants to merge 1 commit into
collective:main from
Mohammed-Ahmed7:fix/calendar-doc-links

Conversation

@Mohammed-Ahmed7

@Mohammed-Ahmed7 Mohammed-Ahmed7 commented Aug 27, 2026 •
edited
Loading

Copy link
Copy Markdown

Linked issue

Description

Fixed two broken documentation links in the Calendar.new docstring
(calendar.py). The Availability class reference was missing its
full module path, so Sphinx couldn't resolve it. The DEFAULT_PRODID
reference pointed to an undocumented module-level constant with no
linkable target, so it was changed to plain code formatting instead —
confirmed against the style guide and issue #1072, neither of which
documents a way to link module-level constants.

Verified locally with a Sphinx nitpicky build: warnings dropped from
70 to 68, both references now render correctly. Also ran the full
test suite; two unrelated pre-existing failures were found (external
link rot in linkcheck, and a local timezone-database quirk on my
machine) — neither relates to this change.

No test added: this fix corrects a Sphinx cross-reference syntax
error in a docstring, which the pytest suite doesn't cover — it's
verified via the Sphinx nitpicky build instead (see above).

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.

@github-actions github-actions Bot added the ai-suspicion This contribution is possibly created with lots of AI help without enough human understanding. label Aug 27, 2026

Copy link
Copy Markdown
Contributor

This pull request did not pass quality checks and AI use is suspected. Please review Contribute and make any necessary amendments.

Copy link
Copy Markdown
Contributor

Profile summary:

GitHub user: Mohammed-Ahmed7
🟢 No concerns found with user's profile.
🟢 No concerns found with recent PR activity.
🟢 No concerns found with recent issue activity.
For a more detailed report, run `gh-profiler Mohammed-Ahmed7`.
Full profile 
GitHub user: Mohammed-Ahmed7
🟢 No concerns found with user's profile.
 🟢 Account age: 1 year, 1 month
 🟢 Profile information:
 name: Mohammed Ahmed
 company: Moah Media
 blog: https://moah-media.de/
 location: germany
 Empty fields: email, bio
🟢 No concerns found with recent PR activity.
 1 PR opened in the last 21 days.
 0 opened against repos the user owns.
 0 opened against repos in publicly associated orgs.
 1 opened against external repos.
 🟢 0 of 1 external PRs merged in the last 21 days.
 🟢 0 of 1 external PRs closed without merging in the last 21 days.
🟢 No concerns found with recent issue activity.
 🟢 No new issues opened in the last 21 days.

read-the-docs-community Bot commented Aug 27, 2026 •
edited
Loading

Copy link
Copy Markdown

Documentation build overview

📚 icalendar | 🛠️ Build #34266606 | 📁 Comparing 051ecd4 against latest (9e2e416)

🔍 Preview build

1 file changed
± _modules/icalendar/cal/calendar.html 

Availability was missing its full module path. DEFAULT_PRODID
pointed to an undocumented constant; replaced with plain code
formatting instead.
AI: Claude Sonnet 5 (via Claude Code), used as a tutor to learn
Sphinx link syntax and verify the build. I wrote, edited, and
verified all changes myself.

@stevepiercy stevepiercy left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Mohammed-Ahmed7 thanks for your contribution. It made me think it would be shame not to link to DEFAULT_PRODID, so see what I suggested. Also there's a shorthand syntax, and the news should be updated to align with the suggestions. Would you please take care?



DEFAULT_PRODID = f"-//collective//icalendar//{__version__}//EN"

@stevepiercy stevepiercy Aug 28, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, let's document this value. Then the link works.

Suggested change
"""The value for :attr:`~icalendar.cal.calendar.Calendar.prodid` when it's not provided."""

generates a `prodid` in the format of "-//organization//name//language".
If ``None`` and ``organization`` is not provided, sets it to
:attr:`~icalendar.cal.calendar.DEFAULT_PRODID`.
``DEFAULT_PRODID``.

@stevepiercy stevepiercy Aug 28, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please revert this change, and see my suggestion above.

https://github.com/collective/icalendar/pull/1732/changes#r3879155959

@property
def availabilities(self) -> list[Availability]:
"""All :class:`Availability` components in the calendar.
"""All :class:`Availability <icalendar.cal.availability.Availability>` components in the calendar.

@stevepiercy stevepiercy Aug 28, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See the "object only" syntax example at https://icalendar.readthedocs.io/en/latest/contribute/documentation/style-guide.html#cross-reference-python-objects.

Suggested change
"""All :class:`Availability <icalendar.cal.availability.Availability>` components in the calendar.
"""All :class:`~icalendar.cal.availability.Availability` components in the calendar.

Comment thread news/1158.documentation
Comment on lines +1 to +10
Fixed two broken documentation cross-reference links in the
:meth:`~icalendar.cal.calendar.Calendar.new` docstring: the
:class:`~icalendar.cal.availability.Availability` class reference
was missing its full module path, and the ``DEFAULT_PRODID``
reference pointed to an undocumented module-level constant and
was changed to plain code formatting instead.

I used AI to assist me with this change.

@Mohammed-Ahmed7

@stevepiercy stevepiercy Aug 28, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please put this on a single line, and update it to reflect the suggestions below.

Copy link
Copy Markdown
Member

@Mohammed-Ahmed7 would you please:

Thank you!

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

Reviewers

@stevepiercy stevepiercy stevepiercy requested changes
@niccokunzmann niccokunzmann Awaiting requested review from niccokunzmann niccokunzmann is a code owner
@SashankBhamidi SashankBhamidi Awaiting requested review from SashankBhamidi
@angatha angatha Awaiting requested review from angatha angatha is a code owner

Requested changes must be addressed to merge this pull request.

Labels

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

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

AltStyle によって変換されたページ (->オリジナル) /