Skip to content

gh-108202: Document calendar.Calendar methods getfirstweekday and setfirstweekday #127579

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 19 commits into from
Jan 6, 2025
Merged

gh-108202: Document calendar.Calendar methods getfirstweekday and setfirstweekday #127579

merged 19 commits into from
Jan 6, 2025

Conversation

StanFromIreland
Copy link
Contributor

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

#108202

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/

@StanFromIreland
Document getfirstweekday and setfirstweekday

Verified

This commit was signed with the committer’s verified signature. The key has expired.
spinda Naomi Smith
GPG key ID: 8645BDF574E8F755
Expired
Verified
Learn about vigilant mode
e46405e
@bedevere-app bedevere-app bot mentioned this pull request Dec 3, 2024
Open
@bedevere-app bedevere-app bot added docs Documentation in the Doc dir skip news awaiting review labels Dec 3, 2024
@erlend-aasland
Copy link
Contributor

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
Copy link
Contributor

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

@ZeroIntensity ZeroIntensity added needs backport to 3.12 only security fixes needs backport to 3.13 bugs and security fixes labels Dec 4, 2024
StanFromIreland and others added 3 commits December 4, 2024 16:03
@StanFromIreland @ZeroIntensity
Update Doc/library/calendar.rst

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Verified
Learn about vigilant mode
de386b9 
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
@StanFromIreland
Update calendar.rst

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Verified
Learn about vigilant mode
3e1edc4
@StanFromIreland
Update calendar.rst

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Verified
Learn about vigilant mode
ee2a8a2
@StanFromIreland
Copy link
Contributor Author

StanFromIreland commented Dec 4, 2024 •
edited
Loading

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?

@StanFromIreland
Merge branch 'main' into patch-3

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Verified
Learn about vigilant mode
86dfef7
@StanFromIreland
Remove trailing whitespace

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Verified
Learn about vigilant mode
a0a7ba0
@StanFromIreland
Update calendar.rst

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Verified
Learn about vigilant mode
ffbc567
@StanFromIreland
Update calendar.rst
86a39c4
@StanFromIreland
Update calendar.rst
9096b51
@eendebakpt
Copy link
Contributor

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.

StanFromIreland and others added 2 commits December 17, 2024 16:36
@StanFromIreland @eendebakpt
Update Doc/library/calendar.rst
692a29c 
Co-authored-by: Pieter Eendebak <pieter.eendebak@gmail.com>
@StanFromIreland
Update calendar.rst
342c396
@StanFromIreland
Copy link
Contributor Author

Added :no-index:.

@StanFromIreland
Copy link
Contributor Author

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

erlend-aasland
erlend-aasland reviewed Jan 5, 2025
View reviewed changes
StanFromIreland and others added 5 commits January 6, 2025 17:52
@StanFromIreland @erlend-aasland
Update Doc/library/calendar.rst
156c418 
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
@StanFromIreland @erlend-aasland
Update Doc/library/calendar.rst
ab7cba5 
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
@StanFromIreland @erlend-aasland
Update Doc/library/calendar.rst
4e587c8 
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
@StanFromIreland
Update calendar.rst
95f9fae
@erlend-aasland
Address review
67201be
@erlend-aasland erlend-aasland changed the title gh-108202: calendar: Document getfirstweekday and setfirstweekday gh-108202: Document calendar.Calendar methods getfirstweekday and setfirstweekday Jan 6, 2025
@erlend-aasland
Copy link
Contributor

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.

@erlend-aasland erlend-aasland merged commit 953b49e into python:main Jan 6, 2025
29 checks passed
@miss-islington-app

This comment was marked as outdated.

Sign in to view
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jan 6, 2025
@StanFromIreland @miss-islington
pythongh-108202: Document calendar.Calendar methods `getfirstweekda…
Loading
Loading status checks…
9e1f1ff 
…y` and `setfirstweekday` (pythonGH-127579)

(cherry picked from commit 953b49e)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
@bedevere-app
Copy link

bedevere-app bot commented Jan 6, 2025

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jan 6, 2025
@StanFromIreland @miss-islington
pythongh-108202: Document calendar.Calendar methods `getfirstweekda…
Loading
Loading status checks…
82f16d1 
…y` and `setfirstweekday` (pythonGH-127579)

(cherry picked from commit 953b49e)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
@bedevere-app bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Jan 6, 2025
@bedevere-app
Copy link

bedevere-app bot commented Jan 6, 2025

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

@bedevere-app bedevere-app bot removed the needs backport to 3.12 only security fixes label Jan 6, 2025
erlend-aasland pushed a commit that referenced this pull request Jan 6, 2025
@miss-islington @StanFromIreland
[3.13] gh-108202: Document calendar.Calendar methods `getfirstweekd…
d81b99b 
…ay` and `setfirstweekday` (GH-127579) (#128564)

(cherry picked from commit 953b49e)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
erlend-aasland pushed a commit that referenced this pull request Jan 6, 2025
@miss-islington @StanFromIreland
[3.12] gh-108202: Document calendar.Calendar methods `getfirstweekd…
fb8bb36 
…ay` and `setfirstweekday` (GH-127579) (#128565)

(cherry picked from commit 953b49e)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
@erlend-aasland erlend-aasland mentioned this pull request Jan 6, 2025
Merged
srinivasreddy pushed a commit to srinivasreddy/cpython that referenced this pull request Jan 8, 2025
@StanFromIreland @srinivasreddy
pythongh-108202: Document calendar.Calendar methods `getfirstweekda…
1d65bf6 
…y` and `setfirstweekday` (python#127579)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@erlend-aasland erlend-aasland

@ZeroIntensity ZeroIntensity

@eendebakpt eendebakpt

Assignees
No one assigned
Labels
docs Documentation in the Doc dir skip news
Projects
Docs PRs
Status: Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
4 participants
@StanFromIreland @erlend-aasland @eendebakpt @ZeroIntensity