◐ Shell
reader mode source ↗
Skip to content

gh-101100: Fix sphinx warnings in enum module#101122

Merged
ethanfurman merged 4 commits into
python:mainfrom
sobolevn:fix-enum-docs
Jan 20, 2023
Merged

gh-101100: Fix sphinx warnings in enum module#101122
ethanfurman merged 4 commits into
python:mainfrom
sobolevn:fix-enum-docs

Conversation

@sobolevn

@sobolevn sobolevn commented Jan 18, 2023 •
edited by bedevere-bot
Loading

Copy link
Copy Markdown
Member

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:

Снимок экрана 2023-01-18 в 11 18 28

Снимок экрана 2023-01-18 в 11 18 38

Снимок экрана 2023-01-18 в 11 19 57

Снимок экрана 2023-01-18 в 11 21 18

After the fix, there are no warnings:

Снимок экрана 2023-01-18 в 11 27 00

@sobolevn sobolevn requested a review from ethanfurman as a code owner January 18, 2023 08:30
@bedevere-bot bedevere-bot mentioned this pull request Jan 18, 2023
Open
@bedevere-bot bedevere-bot added docs Documentation in the Doc dir skip news labels Jan 18, 2023
CAM-Gerlach
CAM-Gerlach requested changes Jan 19, 2023
View reviewed changes

@CAM-Gerlach CAM-Gerlach left a comment •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hide comment

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 CAM-Gerlach added needs backport to 3.10 only security fixes needs backport to 3.11 only security fixes labels Jan 19, 2023
@CAM-Gerlach

CAM-Gerlach commented Jan 19, 2023

Copy link
Copy Markdown
Member

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

sobolevn commented Jan 19, 2023

Copy link
Copy Markdown
Member Author

@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
CAM-Gerlach reviewed Jan 20, 2023
View reviewed changes

@CAM-Gerlach CAM-Gerlach left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hide comment

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

CAM-Gerlach commented Jan 20, 2023

Copy link
Copy Markdown
Member

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 and others added 2 commits January 19, 2023 18:07
@ethanfurman @CAM-Gerlach
Apply suggestions from code review …
440385f 
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
@ethanfurman @CAM-Gerlach
Update Doc/library/enum.rst …
8f5716e 
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
ethanfurman
ethanfurman approved these changes Jan 20, 2023
View reviewed changes

@ethanfurman ethanfurman left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hide comment

Looks good, thank you both!

@ethanfurman ethanfurman removed the needs backport to 3.10 only security fixes label Jan 20, 2023
@ethanfurman

ethanfurman commented Jan 20, 2023

Copy link
Copy Markdown
Member

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

@ethanfurman ethanfurman merged commit 9e025d3 into python:main Jan 20, 2023
@miss-islington

miss-islington commented Jan 20, 2023

Copy link
Copy Markdown
Contributor

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jan 20, 2023
@sobolevn @CAM-Gerlach @miss-islington
pythongh-101100: [Enum] Fix sphinx warnings in docs (pythonGH-101122) …
255276b 
* pythongh-101100: [Enum] Fix sphinx warnings in

(cherry picked from commit 9e025d3)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
@bedevere-bot

bedevere-bot commented Jan 20, 2023

Copy link
Copy Markdown

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

ambv pushed a commit that referenced this pull request Jan 20, 2023
@miss-islington @sobolevn @CAM-Gerlach
[3.11] gh-101100: [Enum] Fix sphinx warnings in docs (GH-101122) (#10… …
e039d53 
…1173)

(cherry picked from commit 9e025d3)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@CAM-Gerlach CAM-Gerlach CAM-Gerlach requested changes

@ethanfurman ethanfurman ethanfurman approved these changes

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@sobolevn @CAM-Gerlach @ethanfurman @miss-islington @bedevere-bot