docs: fix broken cross-references in documentation by wahajahmed010 · Pull Request #1369 · collective/icalendar

wahajahmed010 · 2026-05-07T22:14:36Z

Changes

Remove :py: prefix from cross-references in docstrings:
- :py:class: → :class:
- :py:mod: → :mod:
- :py:meth: → :meth:
Fix unqualified references to use fully qualified names:
- :class:BUSYTYPE → `:class:`icalendar.enums.BUSYTYPE
- :class:FBTYPE → `:class:`icalendar.enums.FBTYPE
- :func:_escape_char → `:func:`~icalendar.parser.string._escape_char
- ...and more
Use tilde-prefixed references (~) for cleaner displayed text while maintaining correct linking.

Files changed (13)

src/icalendar/cal/calendar.py
src/icalendar/cal/lazy.py
src/icalendar/cal/todo.py
src/icalendar/caselessdict.py
src/icalendar/enums.py
src/icalendar/parser/ical/lazy.py
src/icalendar/parser/parameter.py
src/icalendar/parser/property.py
src/icalendar/parser/string.py
src/icalendar/prop/dt/date.py
src/icalendar/prop/dt/datetime.py
src/icalendar/prop/dt/duration.py
src/icalendar/prop/dt/time.py

This PR was AI-assisted.

📚 Documentation preview 📚: https://icalendar--1369.org.readthedocs.build/

Fixes collective#1158 - Remove :py: prefix from cross-references in docstrings (:py:class: -> :class:, :py:mod: -> :mod:, :py:meth: -> :meth:) - Fix unqualified references to use fully qualified names (e.g. :class:`BUSYTYPE` -> :class:`icalendar.enums.BUSYTYPE`) - Use tilde-prefixed references for cleaner display (:class:`~icalendar.cal.todo.Todo`) - Affected files: calendar.py, lazy.py, todo.py, caselessdict.py, enums.py, parser/ical/lazy.py, parser/parameter.py, parser/property.py, parser/string.py, prop/dt/date.py, prop/dt/datetime.py, prop/dt/duration.py, prop/dt/time.py

read-the-docs-community · 2026-05-07T22:18:15Z

Documentation build overview

📚 icalendar | 🛠️ Build #32687877 | 📁 Comparing 70440f3 against latest (7357cec)

🔍 Preview build

22 files changed · ± 22 modified

± Modified

stevepiercy · 2026-05-14T03:54:19Z

@wahajahmed010 would you please:

Replace "Fixes" with "See" in your PR description, as there may be other items that haven't been addressed and the issue should remain open
Update your branch against main
Fix code style with ruff
Resolve any change conflicts
Add a change log entry

For details, see https://icalendar.readthedocs.io/en/stable/contribute/index.html and https://icalendar.readthedocs.io/en/stable/contribute/development.html.

Once you perform those tasks, then I'll do a review. Thank you!

wahajahmed010 · 2026-05-14T11:31:37Z

@stevepiercy Thanks for the review! I've addressed all your feedback:

✅ Changed 'Fixes' → 'See' in the PR description
✅ Rebased on main
✅ Fixed ruff style errors (E501 line-length in docstrings)
✅ Resolved merge conflicts
✅ Added changelog entry

Ready for another review! 🙏

stevepiercy · 2026-05-21T01:06:57Z

 Minor changes
 ~~~~~~~~~~~~~

+- Fix broken cross-references in documentation by replacing ``:py:`` prefixed roles with standard Sphinx roles and qualifying ambiguous references. See `#1158 <https://github.com/collective/icalendar/issues/1158>`_


Please edit and move this to a new file at /news/1158.documentation. In v7.1.1, we migrated to an automated procedure to update CHANGES.rst, per https://icalendar.readthedocs.io/en/latest/contribute/index.html#change-log-entry-format. This also avoids merge conflicts and updating your PR repeatedly while waiting for it to get merged.

Suggested change

- Fix broken cross-references in documentation by replacing ``:py:`` prefixed roles with standard Sphinx roles and qualifying ambiguous references. See `#1158 <https://github.com/collective/icalendar/issues/1158>`_

- Fix broken cross-references in documentation by removing ``:py`` prefixed roles and qualifying ambiguous references. @wahajahmed010

I'll perform a full review later.

stevepiercy

Thank you for your contribution! This is an improvement, but some things need to be reverted. I'll explain.

Python objects without a fully qualified path are in the context of the module, whether that's in docstrings or code, and it's not ambiguous. Adding a fully qualified path adds visual noise to readers of the source code, and it doesn't change how the link functions. Such links weren't broken and didn't need to be changed.

You did catch one incorrect and ambiguous reference, though, and that was well-spotted.

Would you please take care? Thank you!

stevepiercy · 2026-05-21T01:44:52Z

            True

-        When you access all :attr:`subcomponents` of the calendar,
+        When you access all :attr:`~icalendar.cal.component.Component.subcomponents` of the calendar,


Good catch! It previously linked to https://icalendar.readthedocs.io/en/latest/reference/api/icalendar.cal.lazy.html#icalendar.cal.lazy.LazyCalendar.subcomponents, which is not the greater context of all components.

stevepiercy · 2026-05-21T01:53:08Z

    r"""Unescape backslash sequences in iCalendar text.

-    Unlike :py:meth:`unescape_string`, this only handles actual backslash escapes
+    Unlike :meth:`unescape_string`, this only handles actual backslash escapes


This doesn't fix the link as is. See https://icalendar--1369.org.readthedocs.build/en/1369/reference/api/icalendar.parser.property.html#icalendar.parser.property.unescape_backslash. This should fix it.

Suggested change

Unlike :meth:`unescape_string`, this only handles actual backslash escapes

Unlike :meth:`~icalendar.parser.string.unescape_string`, this only handles actual backslash escapes

stevepiercy · 2026-05-21T02:01:11Z


        Returns:
-            :class:`Todo`
+            :class:`~icalendar.cal.todo.Todo`


Unnecessary. Please revert.

Suggested change

:class:`~icalendar.cal.todo.Todo`

:class:`Todo`

stevepiercy · 2026-05-21T02:02:58Z

+        Call :meth:`~icalendar.parser.ical.lazy.LazySubcomponent.parse` to get the fully
+        parsed component.


Unnecessary. Please revert.

Suggested change

Call :meth:`~icalendar.parser.ical.lazy.LazySubcomponent.parse` to get the fully

parsed component.

Call :meth:`parse` to get the fully parsed component.

stevepiercy · 2026-05-21T02:04:13Z

+    Joins list items with the separator, applying
+    :func:`~icalendar.parser.parameter.dquote` to each item


Unnecessary. Please revert.

Suggested change

Joins list items with the separator, applying

:func:`~icalendar.parser.parameter.dquote` to each item

Joins list items with the separator, applying :func:`dquote` to each item

stevepiercy · 2026-05-21T02:04:37Z

+    Applies :func:`~icalendar.parser.string._unescape_string` to the value. If the value
+    is a list,


Unnecessary. Please revert.

Suggested change

Applies :func:`~icalendar.parser.string._unescape_string` to the value. If the value

is a list,

Applies :func:`_unescape_string` to the value. If the value is a list,

stevepiercy · 2026-05-21T02:06:47Z

Please revert all changes to this file. They aren't necessary. Private functions don't render as links. The one public function is not ambiguous and its link works as is.

stevepiercy · 2026-05-21T02:07:44Z

Pleasse revert all changes to this file. They aren't necessary.

stevepiercy · 2026-05-21T02:13:54Z

Pleasse revert all changes to this file. They aren't necessary.

wahajahmed010 requested review from SashankBhamidi, angatha, niccokunzmann and stevepiercy as code owners May 7, 2026 22:14

fix: resolve ruff E501 line-length errors and add changelog entry

70440f3

stevepiercy requested changes May 21, 2026

View reviewed changes

stevepiercy mentioned this pull request May 21, 2026

Revise pull request template for issue linking #1394

Open

stevepiercy requested changes May 21, 2026

View reviewed changes

	- Fix broken cross-references in documentation by replacing ``:py:`` prefixed roles with standard Sphinx roles and qualifying ambiguous references. See `#1158 <https://github.com/collective/icalendar/issues/1158>`_
	- Fix broken cross-references in documentation by removing ``:py`` prefixed roles and qualifying ambiguous references. @wahajahmed010

	Unlike :meth:`unescape_string`, this only handles actual backslash escapes
	Unlike :meth:`~icalendar.parser.string.unescape_string`, this only handles actual backslash escapes

		Call :meth:`~icalendar.parser.ical.lazy.LazySubcomponent.parse` to get the fully
		parsed component.

	Call :meth:`~icalendar.parser.ical.lazy.LazySubcomponent.parse` to get the fully
	parsed component.
	Call :meth:`parse` to get the fully parsed component.

		Joins list items with the separator, applying
		:func:`~icalendar.parser.parameter.dquote` to each item

		Applies :func:`~icalendar.parser.string._unescape_string` to the value. If the value
		is a list,

	Applies :func:`~icalendar.parser.string._unescape_string` to the value. If the value
	is a list,
	Applies :func:`_unescape_string` to the value. If the value is a list,

Uh oh!

Conversation

wahajahmed010 commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Files changed (13)

Uh oh!

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

Uh oh!

Documentation build overview

Uh oh!

stevepiercy commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wahajahmed010 commented May 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

wahajahmed010 commented May 7, 2026 •

edited

Loading

read-the-docs-community Bot commented May 7, 2026 •

edited

Loading

stevepiercy commented May 14, 2026 •

edited

Loading