gh-136672: Docs: Move parts of Enum HOWTO to API Docs #139176
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
To avoid duplicate content in the Enum HOWTO and API documentation which is not automatically synced, the section about supported __dunder__ and _sunder names is moved from HOWTO to API docs. See also python#136791
Before this change, the section "Finer Points" was a subsection of "When to use __new__() vs. __init__()" which does not make much sense. This change moves "Finer Points" one level out making it a top level section. All its subsections are moved as well.
The Enum members listed in the sections of `__dunder__` and `_sunder_` did not have version indicators in the API docs. This changes adds the version indicators mentioned in the `__dunder__` and `_sunder_` section to the corresponding Enum member.
bedevere-app
bot
added
awaiting review
docs
RafaelWO
changed the title
This changes moves a note for the Enum member `_generate_next_value_` from the `_sunder_` section to the API section. The intention is to let `_sunder_` section list all members but have the details in the API section.
RafaelWO
force-pushed
the
change/enum-docs-howto-to-api
branch
from
fc092d3 to
ff84f94
Compare
AA-Turner
added
needs backport to 3.13
Contributor
Author
|
@ethanfurman any chance you have time for a review? thanks! 🙂 |
ethanfurman
reviewed
Jan 7, 2026
ethanfurman
approved these changes
Jan 8, 2026
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds the changes discussed in #136791 that were missed before merging (see this comment) to the Enum documentation. That is, removing the duplicated sections
__dunder__and_sunder_names from the Enum HOWTO to the API documentation.Additionally, the "Finer Points" heading on the Enum HOWTO page is moved one level out:
Finally, version indicators mentioned in the
__dunder__and_sunder_sections are added to the corresponding Enum member in the API docs. Also, a note for the Enum member_generate_next_value_is moved from the_sunder_section to the API section..📚 Documentation preview 📚: https://cpython-previews--139176.org.readthedocs.build/