docs: Fix broken cross-references to Python objects across the codebase by morning-verlu · Pull Request #1679 · collective/icalendar

morning-verlu · 2026-08-18T05:00:52Z

Summary

This PR fixes broken Sphinx cross-references to Python objects throughout the source code, addressing issue #1158.

Changes

Short-form `~error.` references → `~icalendar.error.`

Fixed ~error.JCalParsingError, ~error.InvalidCalendar, and ~error.IncompleteComponent references to use the fully qualified ~icalendar.error. path in 28 files across src/icalendar/.

Re-exported `~icalendar.Component.` references → `~icalendar.cal.component.Component.`

Fixed 32 references that used the re-exported icalendar.Component path instead of the actual module path icalendar.cal.component.Component. Affected files include event.py, journal.py, todo.py, available.py, and others.

Unqualified class/method references

:class:BUSYTYPE → `:class:`~icalendar.enums.BUSYTYPE in enums.py
:class:FBTYPE → `:class:`~icalendar.enums.FBTYPE in enums.py
:class:vBoolean → `:class:`~icalendar.prop.boolean.vBoolean in boolean.py
:meth:Component.from_ical → `:meth:`~icalendar.cal.component.Component.from_ical in categories.py
:func:Component.from_jcal → `:func:`~icalendar.cal.component.Component.from_jcal in factory.py and component.py

Verification

All references now use fully qualified names so Sphinx can resolve them correctly in the generated documentation.

Contributes to #1158.

github-actions · 2026-08-18T05:01:01Z

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

github-actions · 2026-08-18T05:01:17Z

Profile summary:

GitHub user: morning-verlu
🔴 Significant concerns found with user's profile.
🟡 Some concerns found with recent PR activity.
🟢 No concerns found with recent issue activity.

For a more detailed report, run `gh-profiler morning-verlu`.

Full profile

GitHub user: morning-verlu
🔴 Significant concerns found with user's profile.
   🟡 Account age: 6 months
   🔴 No profile information provided.

🟡 Some concerns found with recent PR activity.
   14 PRs opened in the last 21 days.
      0 opened against repos the user owns.
      0 opened against repos in publicly associated orgs.
      14 opened against external repos.

   🟡 3 of 14 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 · 2026-08-18T05:02:02Z

Documentation build overview

📚 icalendar | 🛠️ Build #34348775 | 📁 Comparing 7057ca9 against latest (b839275)

🔍 Preview build

81 files changed · ± 81 modified

± Modified

stevepiercy · 2026-08-18T09:13:30Z

@morning-verlu would you please address the failing CI checks? We don't review PRs until they pass all these checks.

stevepiercy

Thanks for you contribution! It fixes several things, but I found a couple of instances that need special attention. Would you please take care?

stevepiercy · 2026-08-18T20:37:50Z

@@ -0,0 +1 @@
+Fixed broken Sphinx cross-references to Python objects throughout the codebase, including ``~error.``, ``~icalendar.Component.``, and unqualified class/method references.


Note that ~error.InvalidCalendar under a Raises section heading in a docstring is perfectly valid syntax and is not "broken." See https://icalendar.readthedocs.io/en/latest/reference/api/icalendar.cal.alarm.html#icalendar.cal.alarm.Alarm.new. This is a standardization.

However, AI is not intelligent despite its name, and will continue to force the issue, and I reckon that it's slightly more helpful to the reader of source code, so I'll go along with it.

Adjusted the news fragment accordingly, and give yourself credit.

Suggested change

Fixed broken Sphinx cross-references to Python objects throughout the codebase, including ``~error.``, ``~icalendar.Component.``, and unqualified class/method references.

Fixed broken and standardized Sphinx cross-references to Python objects throughout the code base, including ``~icalendar.Component.``, unqualified class and method references, and ``~error.``. @morning-verlu

Also please rename this file to 1158.documentation.2 to automatically generate a link to the issue when the news fragments are compiled into the change log. Thank you!

stevepiercy · 2026-08-18T20:40:58Z

        Parameters:
            categories: The :attr:`categories` of the Available component.
-            comments: The :attr:`~icalendar.Component.comments` of the Available
+            comments: The :attr:`~icalendar.cal.component.Component.comments` of the Available


All these parameters look much better now. Thank you!

stevepiercy · 2026-08-18T20:46:30Z


    Returns:
-        A new :class:`vBoolean` instance with the supplied property parameters.
+        A new :class:`~icalendar.prop.boolean.vBoolean` instance with the supplied property parameters.


This is another example that standardizes the working link. Both forms are valid. See https://icalendar.readthedocs.io/en/latest/reference/api/icalendar.prop.boolean.html.

stevepiercy · 2026-08-18T20:49:42Z

        """Parse a CATEGORIES value from iCalendar format.

-        This helper is normally called by :meth:`Component.from_ical`, which
+        This helper is normally called by :meth:`~icalendar.cal.component.Component.from_ical`, which


The original syntax didn't link, so well-spotted! However, here we want to preserve the display of the last two segments of the dotted path to disambiguate which from_ical is called throughout the code base.

Suggested change

This helper is normally called by :meth:`~icalendar.cal.component.Component.from_ical`, which

This helper is normally called by :meth:`Component.from_ical <icalendar.cal.component.Component.from_ical>`, which

stevepiercy · 2026-08-18T20:50:22Z

        Parameters:
            ical: A list of category strings (preferred, as provided by
-                :meth:`Component.from_ical`), or a single comma-separated
+                :meth:`~icalendar.cal.component.Component.from_ical`), or a single comma-separated


Suggested change

:meth:`~icalendar.cal.component.Component.from_ical`), or a single comma-separated

:meth:`Component.from_ical <icalendar.cal.component.Component.from_ical>`), or a single comma-separated

stevepiercy · 2026-08-18T20:52:18Z

        ``"date-time"`` for ``DTSTART`` or ``"duration"`` for ``TRIGGER``.
        This is the value type a property uses when no explicit ``VALUE``
-        parameter is given, so it tells :func:`Component.from_jcal` whether a
+        parameter is given, so it tells :func:`~icalendar.cal.component.Component.from_jcal` whether a


This is actually a method, being under a class.

Suggested change

parameter is given, so it tells :func:`~icalendar.cal.component.Component.from_jcal` whether a

parameter is given, so it tells :meth:`Component.from_ical <icalendar.cal.component.Component.from_ical>` whether a

stevepiercy · 2026-08-19T00:38:37Z

@morning-verlu would you please resolve the merge conflicts as well? We can't merge until that's done. Thank you!

niccokunzmann

Ready for merge after @stevepiercy's suggestions. Since this covers a lot of places, let's get it merged quickly to avoid spending time on merge conflicts.

Fix unqualified and short-form Sphinx cross-references throughout the codebase so that documentation links resolve correctly: - Replace ~error.X with ~icalendar.error.X (JCalParsingError, InvalidCalendar, IncompleteComponent) in 28 source files - Replace ~icalendar.Component.attr with ~icalendar.cal.component.Component.attr in 32 references - Qualify :class:BUSYTYPE and :class:FBTYPE in enums.py - Qualify :class:vBoolean in boolean.py - Qualify :meth:Component.from_ical in categories.py - Qualify :func:Component.from_jcal in factory.py and component.py Contributes to collective#1158

coveralls-official · 2026-09-02T08:34:56Z

coverage: 97.536%. remained the same — morning-verlu:fix/broken-doc-references into collective:main

morning-verlu · 2026-09-02T08:36:20Z

Rebased onto the current main branch and resolved the merge conflicts. The refreshed documentation, ruff, test, fuzzing, and package checks are all passing now.

niccokunzmann · 2026-09-02T19:22:22Z

@morning-verlu Please let us know when we should have another look! Are you still working on this or should we review? You can also let us know in the comments above if they have been addressed or if you have a question or idea.

stevepiercy · 2026-09-06T10:29:12Z

@morning-verlu would you please address my review? See #1679 (review)

morning-verlu requested review from SashankBhamidi, angatha, niccokunzmann and stevepiercy as code owners August 18, 2026 05:00

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

stevepiercy requested changes Aug 18, 2026

View reviewed changes

niccokunzmann previously approved these changes Aug 19, 2026

View reviewed changes

niccokunzmann dismissed their stale review via c3e9645 August 19, 2026 12:28

stevepiercy added the doc label Aug 23, 2026

morning-verlu added 2 commits September 2, 2026 16:24

fix: ruff line length and add news fragment

7057ca9

morning-verlu force-pushed the fix/broken-doc-references branch from c3e9645 to 7057ca9 Compare September 2, 2026 08:29

niccokunzmann assigned stevepiercy Sep 2, 2026

This was referenced Sep 5, 2026

[Beginner] Correct broken links to classes & functions in documentation #1158

Open

docs: fix broken Component cross-refs in Available.new #1766

Merged

		@@ -0,0 +1 @@
		Fixed broken Sphinx cross-references to Python objects throughout the codebase, including ``~error.``, ``~icalendar.Component.``, and unqualified class/method references.

	Fixed broken Sphinx cross-references to Python objects throughout the codebase, including ``~error.``, ``~icalendar.Component.``, and unqualified class/method references.
	Fixed broken and standardized Sphinx cross-references to Python objects throughout the code base, including ``~icalendar.Component.``, unqualified class and method references, and ``~error.``. @morning-verlu

	This helper is normally called by :meth:`~icalendar.cal.component.Component.from_ical`, which
	This helper is normally called by :meth:`Component.from_ical <icalendar.cal.component.Component.from_ical>`, which

	:meth:`~icalendar.cal.component.Component.from_ical`), or a single comma-separated
	:meth:`Component.from_ical <icalendar.cal.component.Component.from_ical>`), or a single comma-separated

	parameter is given, so it tells :func:`~icalendar.cal.component.Component.from_jcal` whether a
	parameter is given, so it tells :meth:`Component.from_ical <icalendar.cal.component.Component.from_ical>` whether a

Uh oh!

Uh oh!

Conversation

morning-verlu commented Aug 18, 2026

Summary

Changes

Short-form ~error. references → ~icalendar.error.

Re-exported ~icalendar.Component. references → ~icalendar.cal.component.Component.

Unqualified class/method references

Verification

Uh oh!

github-actions Bot commented Aug 18, 2026

Uh oh!

github-actions Bot commented Aug 18, 2026

Uh oh!

read-the-docs-community Bot commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

stevepiercy commented Aug 18, 2026

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

stevepiercy Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy Aug 19, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy commented Aug 19, 2026

Uh oh!

niccokunzmann left a comment

Choose a reason for hiding this comment

Uh oh!

coveralls-official Bot commented Sep 2, 2026

Uh oh!

morning-verlu commented Sep 2, 2026

Uh oh!

niccokunzmann commented Sep 2, 2026

Uh oh!

stevepiercy commented Sep 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Short-form `~error.` references → `~icalendar.error.`

Re-exported `~icalendar.Component.` references → `~icalendar.cal.component.Component.`

read-the-docs-community Bot commented Aug 18, 2026 •

edited

Loading