docs: convert timezone.py docstrings to Google style - #1387
Conversation
Documentation build overview
3 files changed± 404.html± reference/api/icalendar.cal.timezone.html± _modules/icalendar/cal/timezone.html |
|
@Godzilaa would you please add a change log entry per https://icalendar.readthedocs.io/en/stable/contribute/index.html#change-log-entry-format, and update your branch with |
stevepiercy
left a comment
stevepiercy
left a comment
There was a problem hiding this comment.
Thank you for your contribution! I found a few issues with the original docstrings during my review, as well as a few minor suggestions and corrections. Would you please take care to address them? Thank you!
| """ | ||
| :param tzname: Candidate tzname | ||
| :param tznames: Other tznames | ||
| """Make a tzname unique by appending ``_1``, ``_2``, etc. |
There was a problem hiding this comment.
It doesn't actually increment a count, but merely appends a string to the name. Take a look at the calling function to see what gets passed in here.
| """Make a tzname unique by appending ``_1``, ``_2``, etc. | |
| """Make a tzname unique by appending ``_1``. |
There was a problem hiding this comment.
This was not addressed. Unresolving.
| timezone definitions with tzp. If ``False``, a new timezone | ||
| will be created. If ``True``, the existing timezone will be used | ||
| if it exists, otherwise a new timezone will be created. |
There was a problem hiding this comment.
Make a link to the class, and remove redundant mention of "exist". Also check line length, in case CI fails.
| timezone definitions with tzp. If ``False``, a new timezone | |
| will be created. If ``True``, the existing timezone will be used | |
| if it exists, otherwise a new timezone will be created. | |
| timezone definitions with :class:`~icalendar.timezone.tzp.TZP`. If ``False``, a new timezone | |
| will be created. If ``True``, the existing timezone will be used, | |
| otherwise a new timezone will be created. |
There was a problem hiding this comment.
This was not addressed. Unresolving.
| first_date: A datetime that is earlier than anything that | ||
| happens in the calendar. | ||
| last_date: A datetime that is later than anything that |
There was a problem hiding this comment.
The original docstring was wrong. dates are passed in, not datetimes.
| first_date: A datetime that is earlier than anything that | |
| happens in the calendar. | |
| last_date: A datetime that is later than anything that | |
| first_date: A date that is earlier than anything that | |
| happens in the calendar. | |
| last_date: A date that is later than anything that |
There was a problem hiding this comment.
This was not addressed. Unresolving.
| tzp: The timezone provider. | ||
| first_date: A datetime that is earlier than anything | ||
| that happens in the calendar. | ||
| last_date: A datetime that is later than anything |
There was a problem hiding this comment.
| last_date: A datetime that is later than anything | |
| first_date: A date that is earlier than anything | |
| that happens in the calendar. | |
| last_date: A date that is later than anything |
There was a problem hiding this comment.
This was not addressed. Unresolving.
Convert old :param/:raises Sphinx-style docstrings in timezone.py to Google-style docstrings matching the project style guide. Functions updated: - _extract_offsets - _make_unique_tzname - to_tz - from_tzinfo - from_tzid Contributes to collective#1072 Used AI model: opencode/deepseek-v4-flash-free Used for: converting Sphinx-style docstrings to Google-style, fixing duplicate parameter in from_tzid, adding changelog entry, and fixing line length formatting.
20ceb7d to
4385d4c
Compare
|
I've rebased the branch on latest main, added a changelog entry (news/1072.documentation), fixed the duplicate |
|
@Godzilaa you resolved four suggestions without a comment. I unresolved them. Would you please address them? Thank you! |
|
@Godzilaa there are now merge conflicts that need to be resolve, too. Would you please take care? Thank you! |
|
@Godzilaa thanks for starting the work. Would you please continue the work and resolve the issues I've raised? Please let us know if you need any further help with this. Thank you! |
|
@Godzilaa this PR has had no change for some time. Let me know if you'd like to give it the finishing touch! Otherwise I will close it in a week. |
3 participants
Convert old
:param/:raisesSphinx-style docstrings intimezone.pyto Google-style docstrings matching the project style guide.
Functions updated:
_extract_offsets_make_unique_tznameto_tzfrom_tzinfofrom_tzidContributes to #1072