gh-101100: Fix sphinx warnings in enum module

[sobolevn]

There were several warnings before:

/Users/sobolev/Desktop/cpython/Doc/library/enum.rst:428: WARNING: py:meth reference target not found: __str__
/Users/sobolev/Desktop/cpython/Doc/library/enum.rst:428: WARNING: py:func reference target not found: int.__str__
/Users/sobolev/Desktop/cpython/Doc/library/enum.rst:428: WARNING: py:meth reference target not found: __format__
/Users/sobolev/Desktop/cpython/Doc/library/enum.rst:428: WARNING: py:func reference target not found: int.__format__
/Users/sobolev/Desktop/cpython/Doc/library/enum.rst:764: WARNING: py:attr reference target not found: __members__
/Users/sobolev/Desktop/cpython/Doc/library/enum.rst:767: WARNING: py:meth reference target not found: __new__
/Users/sobolev/Desktop/cpython/Doc/library/enum.rst:767: WARNING: py:attr reference target not found: _value_
/Users/sobolev/Desktop/cpython/Doc/library/enum.rst:806: WARNING: py:meth reference target not found: _generate_next_value_
/Users/sobolev/Desktop/cpython/Doc/library/enum.rst:849: WARNING: py:attr reference target not found: __members__

Here's how these places were rendered:

After the fix, there are no warnings:

• Issue: Fix all Sphinx reference warnings in the documentation #101100

[CAM-Gerlach]

In general, unfortunately none of these changes are actually the correct fix, and many are in fact regressions. Some common themes:

• Method/attribute names should use be literal, not italic (reserved for parameters), and generic object methods/attributes can be either linked with :meth:`~object.__dunder__`, or unlinked with :meth:`!__dunder__` (see the reST markup quick reference in the devguide)
• If the ref target actually exists, ! should not be used unless it would be repeating the same link within the same information unit (paragraph, description block, etc—see python/docs-community#52 )
• If the ref target does not and should not exist, and the original usage did not prefix a method, attribute, etc. name with the class or module it belongs to, and it is unambiguous in context, then it shouldn't be added when making it an unresolved reference (see python/docs-community#52 again)
• If the ref target does not exist, but potentially should be documented, then it is a valid warning that should either be documented or left as-is a rather than silenced (see what we did in sqlite3).

Etc., see individual comments on each change for more details and the suggested fixes to each.

[CAM-Gerlach]

If @ethanfurman prefers these to be verbatim code literals, as you've changed them to, instead of marked-up classes and attributes as they were before, then that's fine—it is a bit of a gray area.

However, in general when you're changing existing text, it seems to make more sense to at least initially propose the more minimal change that retains the previous markup, formatting and rendering, and just disables resolution (silencing the warnings):

Suggested change

	- The class ``Color`` is an *enumeration* (or *enum*)
	- The attributes ``Color.RED``, ``Color.GREEN``, etc., are
	- The class :class:`!Color` is an *enumeration* (or *enum*)
	- The attributes :attr:`!Color.RED`, :attr:`!Color.GREEN`, etc., are

[sobolevn]

I don't quite agree that these references should be :class: and :attr:, because Color is only defined in the docs. But, visual separation is a good enough argument to keep it this way.

[CAM-Gerlach]

Yeah, I think there's a good conceptual argument to be made for either way, and I don't have a particular preference myself—in fact, if anything generally I tend to prefer the style you used, for the reason you mentioned (plus its a little simpler).

However, I ended up mentioning it here because it preserved the existing syntax and styling as much as practical, and in particular because this particular usage is explicitly to highlight the semantic differences between the enum, members, and their names and values, which the markup helps accentuate (in fact, before I saw the next line, I hesitated to make this comment at all).

To note, though, due to a theme CSS bug, references in admonitions (like this note) are rendered with the background anyway—but will start working again as soon as that's fixed.

[CAM-Gerlach]

Same here; why not:

Suggested change

	.. versionchanged:: 3.11 *__str__* is now ``int.__str__`` to
	.. versionchanged:: 3.11 :meth:`~object.__str__` is now :meth:`!int.__str__` to

[sobolevn]

I have slightly modified your proposed change, because reading

:meth:`~object.__str__` is now :meth:`!int.__str__`

does not make much sense to me. Now it is:

:meth:`!__str__` is now :meth:`!int.__str__`

[CAM-Gerlach]

But the latter is essentially what readers will actually see, of course; the ~ removes the object prefix, so the original suggestion already displays as your second example, just with __str__ usefully cross-referenced to a description of the __str__ dunder and what it's used for, which seems to me to be potentially helpful to readers (and surely does no harm, at least).

[CAM-Gerlach]

I don't really get this either. This is a list of supported dunder and sunder names, and none of the other names have the class name explicitly prefixed, so I'm not sure why it makes sense to treat this differently.

Either __members__ should be explicitly documented under EnumType, like a number of other dunders and sunders are (including some listed here), and the link fixed here in the meantime (which displays the same as now until it is added):

Suggested change

	:attr:`!EnumType.__members__` is a read-only ordered mapping of ``member_name``:``member``
	:attr:`~EnumType.__members__` is a read-only ordered mapping of ``member_name``:``member``

or, if for whatever reason it doesn't make sense to explicitly document __members__ in the usual way, silence the warning without the prefix:

Suggested change

	:attr:`!EnumType.__members__` is a read-only ordered mapping of ``member_name``:``member``
	:attr:`!__members__` is a read-only ordered mapping of ``member_name``:``member``

[sobolevn]

Let's document __member__ separately and keep the focus of this PR focused 😉

[CAM-Gerlach]

Sure, but if __members__ should be documented (or the decision left until later), then deresolving it not only silences a valid warning, but also means that it will stay broken even if and when __members__ is documented, rather than start working automatically.

Therefore, unless @ethanfurman has some reason to not explicitly document __members__ but still list it here (which is possible), then the default approach should be the former, i.e. to fix it but leave it resolving, unless and until it is decided to explicitly leave it undocumented.

[CAM-Gerlach]

Also, since this fixes a docs defect and would otherwise increase the change of merge conflicts when backporting other docs fixes, this should be backported as well, at least to 3.11 if not 3.10. To note, the 3.10 backport will likely hit a conflict on one of the lines that's 3.11-specific, but that can be backported manually or with Cherry-Picker.

[sobolevn]

@CAM-Gerlach thanks a lot for teaching me this! It makes so much more sense now.
It is like 10x times better than just going through the https://devguide.python.org/documentation/style-guide/ :)

[CAM-Gerlach]

A few followup suggestions.

(Standard reminder: You can apply the suggestions you want in one go with Files changed -> Add to batch -> Commit, or modify them/add your own and do the same)

[CAM-Gerlach]

I'm so glad it was helpful to you! I was pretty worried that I was too harsh and critical with the tone of my comment, but I'm glad you learned a lot—that's as if not more important than fixing these issues, as it benefits everyone going forward!

[ethanfurman]

Looks good, thank you both!

[ethanfurman]

The enum docs were completely redone in 3.11, so there's no backporting to 3.10.

[miss-islington]

Thanks @sobolevn for the PR, and @ethanfurman for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖

[bedevere-bot]

GH-101173 is a backport of this pull request to the 3.11 branch.