docs: replace RFC copy-paste docstrings with Pythonic docstrings by ykd007 · Pull Request #1385 · collective/icalendar

ykd007 · 2026-05-14T09:48:44Z

Rewrites RFC copy-paste docstrings across Alarm, Component, and Calendar into clean Pythonic format with concise summaries, examples, and see-also references.

Updated (12 properties across 3 files):

Alarm: ACKNOWLEDGED, TRIGGER
Component: DTSTAMP/stamp, LAST_MODIFIED, CREATED
Calendar: calendar_name, description, color, prodid, version, calscale, method, refresh_interval

Validation:

make format
uv run pytest src/icalendar/tests/test_with_doctest.py
make html

read-the-docs-community · 2026-05-14T09:49:37Z

Documentation build overview

📚 icalendar | 🛠️ Build #33613764 | 📁 Comparing 0c2a2a9 against latest (66fb3e1)

🔍 Preview build

82 files changed · + 1 added · ± 81 modified

+ Added

_modules/icalendar/compatibility.html

± Modified

stevepiercy · 2026-05-20T06:55:57Z

@ykd007 would you please resolve the merge conflicts by moving your change log entry into the new format that we adopted in 7.1.2, as documented at https://icalendar.readthedocs.io/en/stable/contribute/index.html#change-log-entry-format?

stevepiercy · 2026-05-20T10:19:00Z

@ykd007 would you also edit your PR description from Closes #1244 to See #1244? We don't want to close it until all the docstrings are checked off the list.

stevepiercy

This is phenomenal work! Thank you!

There are some weird prepended and appended docstrings from a parent method that I'd like to see added to this PR, which will improve other docstrings automatically.

The change log needs to be moved, per the release of 7.1.1, and described in https://icalendar.readthedocs.io/en/stable/contribute/index.html#change-log-entry-format.

Other than that, I pretty much had only grammar and style fixes.

stevepiercy · 2026-05-25T01:01:04Z

@ykd007 in addition to addressing my comments, would you please:

Follow our new change log format, as described in https://icalendar.readthedocs.io/en/stable/contribute/index.html#change-log-entry-format?
Revert your changes to CHANGES.rst? This will also resolve the merge conflicts.

Please let us know if you need assistance with moving this forward. Thank you!

…llective#1385

ykd007 · 2026-05-25T03:04:41Z

Thank you for the detailed feedback, @stevepiercy!

I've pushed two commits addressing your requests:

Reverted CHANGES.rst to match upstream and added a towncrier news fragment at news/1385.documentation following the new format.
Updated the single_utc_property prepended docstring to The {name} property with all values converted to a ``:class:~datetime.datetime in UTC. with proper blank-line separation.
Updated the ACKNOWLEDGED docs first line to match your suggested text.
Cleaned up the p_doc boilerplate in create_single_property to use del/None literals and restructured the parameter note.

Please let me know if anything else needs attention!

stevepiercy · 2026-05-25T03:32:01Z

@ykd007 GitHub shows that there are merge conflicts that need to be resolved. Would you please take care of that? Then I can complete a review and proceed. Thank you!

…llective#1385

ykd007 · 2026-05-25T05:25:13Z

Hi @stevepiercy — I've rebased on current main and resolved all merge conflicts. The branch is clean now. Also tightened a few things during the rebase:

Removed the duplicate :rfc:9074`` reference in the ACKNOWLEDGED docstring
Fixed the invalid :rfc:5545#section-3.8.6.3 role (section anchors aren't supported) to just `:rfc:`5545
Cleaned up the p_doc boilerplate in create_single_property to plain prose instead of a misapplied Parameters section

Should be conflict-free now — please let me know if anything else needs attention.

coveralls · 2026-05-25T05:29:45Z

Coverage Report for CI Build 26384814733

Coverage at 97.784% (no base build to compare)

Details

Coverage remained the same as the base build.
Patch coverage: No coverable lines changed in this PR.
No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

Coverage Stats


Relevant Lines:	12717
Covered Lines:	12440
Line Coverage:	97.82%
Relevant Branches:	778
Covered Branches:	756
Branch Coverage:	97.17%
Branches in Coverage %:	Yes
Coverage Strength:	2.93 hits per line

💛 - Coveralls

stevepiercy

I started to review your changes, but it appears you missed about two dozen of my suggestions and comments. I stopped. Would you please take care of them all? Thank you!

niccokunzmann · 2026-06-21T22:50:25Z

@ykd007 Thanks for your contribution so far. Let us know if you need anything. I know it can sometimes take a bit longer but we would like to see this added :) Please have a look again!

stevepiercy · 2026-06-23T09:12:25Z

@ykd007 there's also some merge conflicts to resolve. I'd like to see your work make it into a release of icalendar. Please let us know if you need any help to get this across the finish line. Thank you!

…lective#1244) Rewrote RFC-verbatim docstrings for the following properties: alarm.py: - Alarm.ACKNOWLEDGED: replaced RFC 9074 Purpose/Description wall-of-text with a concise summary, Return, Example and See also sections. - Alarm.TRIGGER: replaced RFC 5545 Purpose/Value-Type verbatim with a clear summary, type info, Example and See also. component.py: - Component.DTSTAMP / stamp: replaced 'RFC 5545: Conformance/Description' block with a Pythonic summary, context note, Example and See also. - Component.LAST_MODIFIED: same pattern - Pythonic summary, Example, See also. - Component.CREATED: same pattern - Pythonic summary, Example, See also. calendar.py: - Calendar.calendar_name: removed Property Parameters/Conformance/Description RFC headings; added See also. - Calendar.description: same cleanup. - Calendar.color: removed Property Parameters/Conformance/Description RFC headings; added CSS3 link reference and See also. - Calendar.prodid: replaced Conformance/Description verbatim with Pythonic summary, Example and See also. - Calendar.version: replaced Purpose RFC text with Pythonic summary + Example. - Calendar.calscale: replaced Conformance/Description/Compatibility with Pythonic summary, RFC 7529 note, Example and See also. - Calendar.method: replaced Description RFC block with Pythonic summary, iTIP/RFC 5546 reference, Example and See also. - Calendar.refresh_interval: replaced Conformance/Description headings with Pythonic summary, updated Raises, added Example and See also.

…llective#1385

…fix ACKNOWLEDGED and p_doc text

ykd007 · 2026-06-24T16:33:51Z

Thanks for the nudge, @niccokunzmann and @stevepiercy. I rebased the branch on current main and pushed the remaining review cleanup.

I also moved the news fragment to news/1244.documentation, kept CHANGES.rst untouched, applied the pending wording/link/example suggestions, and removed the inline doctest comments from the rendered examples.

Checked locally with:

make format
uv run pytest src/icalendar/tests/test_with_doctest.py
make html

stevepiercy

Thanks for your patience. I found a couple of incorrect RFC section references. I also realized that including section headings in {doc} isn't as helpful as I would like. I'd like your thoughts on this. Please let me know. Thank you!

stevepiercy · 2026-07-16T10:27:05Z

+    Parameters:
+        {", ".join(t.__name__ for t in value_type)}.


A trailing . appeared in the list. Let's remove it.

Suggested change

Parameters:

{", ".join(t.__name__ for t in value_type)}.

Parameters:

{", ".join(t.__name__ for t in value_type)}

I also think that this is too clever. It only gives us the name of the value_types passed in, returned as an unordered list. If we want to support type hints or links to the types, then this is not helpful. I think we ought to move this into each of the properties' docstring instead.

@niccokunzmann can I get your thoughts on this?

There is also __qualname__. That might allow referencing them. That could be worth trying out.

f":class:`{x.__qualname__}`"

The initial idea for me was to create a doc template to reduce time spent on writing, copy&paste errors and ensure consistency. Since you are the docs lead, it is your call if you would rather have proper functions with docstrings and maybe wrappers or calls to ensure good docs.
I am not attached to keeping it like this.
One positive argument for change is that we now start testing the docs for consistency, based on the AST, not generated values.

Yes, also, I think trying to test generated docs will be a layer on top of a layer, which would be an unsupported use case.

Also, I didn't see any type hints on the properties that call create_single_property, only on create_single_property itself. There's also no return type hint on create_single_property, which makes me wonder whether properties should have a Returns docstring heading. What do you think?

There is also __qualname__. That might allow referencing them. That could be worth trying out.

f":class:`{x.__qualname__}`"

Parameters: {", ".join(t.__qualname__ for t in value_type)}

Same result as __name__.

Parameters: {", ".join(":class:`" + t.__qualname__ + "`" for t in value_type)}

Obliterates the Parameters section heading, too. I experimented a little bit to no avail. Ultimately, I think generated docstrings are more trouble than using static docstrings.

stevepiercy · 2026-07-16T10:27:10Z

+
+    Returns:
+        A :class:`~datetime.datetime` or :class:`~datetime.timedelta` if the
+        value is valid. ``None`` if the value is absent.


Oops. The Returns section is not correct for all its usages. See:

https://icalendar--1385.org.readthedocs.build/en/1385/reference/api/icalendar.cal.free_busy.html#icalendar.cal.free_busy.FreeBusy.start

https://icalendar--1385.org.readthedocs.build/en/1385/reference/api/icalendar.cal.free_busy.html#icalendar.cal.free_busy.FreeBusy.end

https://icalendar--1385.org.readthedocs.build/en/1385/reference/api/icalendar.cal.free_busy.html#icalendar.cal.free_busy.FreeBusy.DTSTART

https://icalendar--1385.org.readthedocs.build/en/1385/reference/api/icalendar.cal.free_busy.html#icalendar.cal.free_busy.FreeBusy.DTEND

And that's just one module. There is a total of 14 places where create_single_property is called.

And now that I think about it, does each property actually return anything when it's called? Can it even be called? What do you think?

@niccokunzmann can you add your thoughts on this?

And now that I think about it, does each property actually return anything when it's called? Can it even be called?

@niccokunzmann can you respond to these questions, too? Thank you!

stevepiercy · 2026-07-16T10:37:51Z

+        """The display name of this calendar, per :rfc:`7986#section-5.1`.

-    This implements :rfc:`7986` ``NAME`` and ``X-WR-CALNAME``.
+    Implements both the ``NAME`` property from :rfc:`7986#section-5.3` and the widely used


This was a bad copy-paste by me.

Suggested change

Implements both the ``NAME`` property from :rfc:`7986#section-5.3` and the widely used

Implements both the ``NAME`` property from :rfc:`7986#section-5.1` and the widely used

stevepiercy · 2026-07-16T10:58:00Z

    DTSTAMP = stamp = single_utc_property(
        "DTSTAMP",
-        """RFC 5545:
+        """The UTC datetime stamp recording when this component instance was created or last revised.


It doesn't. 😢 See other comments in attr.py.

ykd007 requested review from SashankBhamidi, angatha, niccokunzmann and stevepiercy as code owners May 14, 2026 09:48

stevepiercy requested changes May 20, 2026

View reviewed changes

ykd007 added a commit to ykd007/ikalendar that referenced this pull request May 25, 2026

fix changelog: revert CHANGES.rst, add towncrier news fragment for co…

ed3c4fb

…llective#1385

ykd007 added a commit to ykd007/ikalendar that referenced this pull request May 25, 2026

fix changelog: revert CHANGES.rst, add towncrier news fragment for co…

6363df5

…llective#1385

ykd007 force-pushed the fix/issue-1244-pythonic-docstrings branch from 86791a0 to ea0101f Compare May 25, 2026 05:25

ykd007 force-pushed the fix/issue-1244-pythonic-docstrings branch from ea0101f to 7c55781 Compare May 25, 2026 06:44

stevepiercy requested changes May 25, 2026

View reviewed changes

Comment thread src/icalendar/attr.py Outdated

Comment thread src/icalendar/attr.py Outdated

Comment thread src/icalendar/attr.py

niccokunzmann assigned stevepiercy Jun 21, 2026

ykd007 and others added 5 commits June 24, 2026 22:02

fix doctests: use ELLIPSIS for tzinfo and str() for vText values

e338510

fix changelog: revert CHANGES.rst, add towncrier news fragment for co…

2755913

…llective#1385

address reviewer suggestions: improve single_utc_property docstring, …

20cbd04

…fix ACKNOWLEDGED and p_doc text

Address remaining docstring review notes

562fb57

ykd007 force-pushed the fix/issue-1244-pythonic-docstrings branch from 7c55781 to 562fb57 Compare June 24, 2026 16:33

niccokunzmann and others added 2 commits July 15, 2026 17:52

Merge branch 'main' into fix/issue-1244-pythonic-docstrings

487f616

Merge branch 'main' into fix/issue-1244-pythonic-docstrings

0c2a2a9

stevepiercy requested changes Jul 16, 2026

View reviewed changes

	Implements both the ``NAME`` property from :rfc:`7986#section-5.3` and the widely used
	Implements both the ``NAME`` property from :rfc:`7986#section-5.1` and the widely used

Uh oh!

Uh oh!

Conversation

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

Uh oh!

Uh oh!

read-the-docs-community Bot commented May 14, 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 20, 2026

Uh oh!

stevepiercy commented May 20, 2026

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stevepiercy commented May 25, 2026

Uh oh!

ykd007 commented May 25, 2026

Uh oh!

stevepiercy commented May 25, 2026

Uh oh!

ykd007 commented May 25, 2026

Uh oh!

coveralls commented May 25, 2026

Coverage Report for CI Build 26384814733

Coverage at 97.784% (no base build to compare)

Details

Uncovered Changes

Coverage Regressions

Coverage Stats

💛 - Coveralls

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

niccokunzmann commented Jun 21, 2026

Uh oh!

stevepiercy commented Jun 23, 2026

Uh oh!

ykd007 commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

ykd007 commented May 14, 2026 •

edited

Loading

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

edited

Loading

ykd007 commented Jun 24, 2026 •

edited

Loading