gh-108202: Document `calendar.Calendar` methods `getfirstweekday` and `setfirstweekday` by StanFromIreland · Pull Request #127579 · python/cpython

StanFromIreland · 2024-12-03T20:53:04Z

This was discussed in the Documentation Community Meeting and as per the issue I have finished documenting the undocumented functions in calendar. I believe .firstweekday is sufficiently referenced in several places already.

📚 Documentation preview 📚: https://cpython-previews--127579.org.readthedocs.build/

erlend-aasland · 2024-12-03T21:30:11Z

I believe .firstweekday is sufficiently referenced in several places already.

Referenced, but still not documented. I think it would make sense to also document the firstweekday attribute in this PR.

erlend-aasland · 2024-12-03T21:33:08Z

See also the discussion following the addition of the firstweekday property:

https://mail.python.org/archives/list/python-dev@python.org/thread/UEKY2MA6MFHP2KQ6B6TMFWXETRAOWGU5/#URCWZKVYAF3S6URR4RWUAMFMQHSMI3IU

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

StanFromIreland · 2024-12-04T16:23:45Z

Referenced, but still not documented. I think it would make sense to also document the firstweekday attribute in this PR.

@erlend-aasland it is now referenced. There however seems to be a conflict between firstweekday and firstweekday() please advise on what to do, should I add :no-index: as is recommended?

eendebakpt · 2024-12-17T09:01:16Z

Referenced, but still not documented. I think it would make sense to also document the firstweekday attribute in this PR.
@erlend-aasland it is now referenced. There however seems to be a conflict between firstweekday and firstweekday() please advise on what to do, should I add :no-index: as is recommended?

Since the firstweekday in the module is (soft) deprecated, I think it makes sense to set :no-index: on that one.

Co-authored-by: Pieter Eendebak <pieter.eendebak@gmail.com>

StanFromIreland · 2024-12-17T16:42:23Z

Added :no-index:.

StanFromIreland · 2025-01-04T10:56:13Z

@erlend-aasland anything I should change with this PR? I modified the introduction as it referenced what I added.

Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

erlend-aasland · 2025-01-06T23:07:50Z

Thanks. Now the PR does what the title says.

As mentioned before (and at the last docs meetup), adding documentation for these undocumented APIs is controversial. I've tried to do so in the past, but had to revert the doc additions because of pushback. I read through the old discussions (dating back to 2006) earlier today; you can find them on the issue at #108202 (comment). It is a heated topic.

I'll quote Serhiy again:

But first than documenting these particular method or two, we should decide whether they should be documented at all.
See past issues with the calendar module. There may be requests for undocumented methods, and some of them may even be rejected already. I think this has already been discussed.

I named my issue deliberately Docs: the calendar module lacks documentation for several APIs, and not Docs: add documentation for missing calendar APIs, because we do not know if we want to add docs for all these APIs. There is no consensus.

…y` and `setfirstweekday` (pythonGH-127579) (cherry picked from commit 953b49e) Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

bedevere-app · 2025-01-06T23:39:01Z

GH-128564 is a backport of this pull request to the 3.13 branch.

…y` and `setfirstweekday` (pythonGH-127579) (cherry picked from commit 953b49e) Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

bedevere-app · 2025-01-06T23:39:07Z

GH-128565 is a backport of this pull request to the 3.12 branch.

…ay` and `setfirstweekday` (GH-127579) (#128564) (cherry picked from commit 953b49e) Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

…ay` and `setfirstweekday` (GH-127579) (#128565) (cherry picked from commit 953b49e) Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

…y` and `setfirstweekday` (python#127579)

Document getfirstweekday and setfirstweekday
e46405e

bedevere-appBot mentioned this pull request Dec 3, 2024
Docs: the calendar module lacks documentation for several APIs #108202
Open

bedevere-appBot added docs Documentation in the Doc dir skip news awaiting review labels Dec 3, 2024

erlend-aasland reviewed Dec 3, 2024
View reviewed changes

Comment threadDoc/library/calendar.rst Outdated

ZeroIntensity reviewed Dec 4, 2024
View reviewed changes

Comment threadDoc/library/calendar.rst Outdated

ZeroIntensity added needs backport to 3.12 only security fixes needs backport to 3.13 bugs and security fixes labels Dec 4, 2024

StanFromIrelandand others added 3 commits December 4, 2024 16:03

Update Doc/library/calendar.rst
de386b9
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

Update calendar.rst
3e1edc4

Update calendar.rst
ee2a8a2

StanFromIreland requested a review from erlend-aasland December 4, 2024 16:23

StanFromIreland added 5 commits December 4, 2024 16:24

Merge branch 'main' into patch-3
86dfef7

Remove trailing whitespace
a0a7ba0

Update calendar.rst
ffbc567

Update calendar.rst
86a39c4

Update calendar.rst
9096b51

eendebakpt reviewed Dec 17, 2024
View reviewed changes

Comment threadDoc/library/calendar.rst Outdated

StanFromIrelandand others added 2 commits December 17, 2024 16:36

Update Doc/library/calendar.rst
692a29c
Co-authored-by: Pieter Eendebak <pieter.eendebak@gmail.com>

Update calendar.rst
342c396

StanFromIreland requested a review from eendebakpt December 17, 2024 16:42

erlend-aasland reviewed Jan 4, 2025
View reviewed changes

Comment threadDoc/library/calendar.rst Outdated

Update calendar.rst
a76f362

StanFromIreland requested a review from erlend-aasland January 4, 2025 13:57

Update calendar.rst
89fb5fd

erlend-aasland reviewed Jan 5, 2025
View reviewed changes

Comment threadDoc/library/calendar.rst Outdated
Comment threadDoc/library/calendar.rst Outdated
Comment threadDoc/library/calendar.rst Outdated
Comment threadDoc/library/calendar.rst Outdated

StanFromIrelandand others added 5 commits January 6, 2025 17:52

Update Doc/library/calendar.rst
156c418
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

Update Doc/library/calendar.rst
ab7cba5
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

Update Doc/library/calendar.rst
4e587c8
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

Update calendar.rst
95f9fae

Address review
67201be

erlend-aasland reviewed Jan 6, 2025
View reviewed changes

Comment threadDoc/library/calendar.rst Outdated

Update calendar.rst
bc42d03

erlend-aasland changed the title ~~gh-108202: calendar: Document getfirstweekday and setfirstweekday~~gh-108202: Document calendar.Calendar methods getfirstweekday and setfirstweekdayJan 6, 2025

erlend-aasland approved these changes Jan 6, 2025
View reviewed changes

bedevere-appBot added awaiting merge and removed awaiting review labels Jan 6, 2025

erlend-aasland merged commit 953b49e into python:mainJan 6, 2025

bedevere-appBot removed the awaiting merge label Jan 6, 2025

This comment was marked as outdated.
Sign in to view

bedevere-appBot removed the needs backport to 3.13 bugs and security fixes label Jan 6, 2025

bedevere-appBot removed the needs backport to 3.12 only security fixes label Jan 6, 2025

erlend-aasland mentioned this pull request Jan 6, 2025
gh-108202: Document calendar.Calendar.firstweekday #128566
Merged

srinivasreddy pushed a commit to srinivasreddy/cpython that referenced this pull request Jan 8, 2025
pythongh-108202: Documentcalendar.Calendarmethods `getfirstweekda…
1d65bf6
…y` and `setfirstweekday` (python#127579)

Uh oh!

Uh oh!

Conversation

StanFromIreland commented Dec 3, 2024• edited by github-actions BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

erlend-aasland commented Dec 3, 2024

Uh oh!

erlend-aasland commented Dec 3, 2024

Uh oh!

Uh oh!

StanFromIreland commented Dec 4, 2024• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

eendebakpt commented Dec 17, 2024

Uh oh!

StanFromIreland commented Dec 17, 2024

Uh oh!

StanFromIreland commented Jan 4, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

erlend-aasland commented Jan 6, 2025

Uh oh!

This comment was marked as outdated.

bedevere-appBot commented Jan 6, 2025

Uh oh!

bedevere-appBot commented Jan 6, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

StanFromIreland commented Dec 3, 2024•
edited by github-actions Bot
Loading

StanFromIreland commented Dec 4, 2024•
edited
Loading