gh-101100: Fix Sphinx reference warnings #112416

hugovk · 2023-11-25T23:27:42Z

Fix 7 Sphinx warnings, in most files with a single warning:

Doc/c-api/set.rst:148: WARNING: py:meth reference target not found: set.discard
Doc/extending/newtypes.rst:295: WARNING: py:attr reference target not found: __doc__
Doc/library/asyncio-stream.rst:263: WARNING: py:meth reference target not found: feed_eof
Doc/library/email.headerregistry.rst:61: WARNING: py:exc reference target not found: email.errors.HeaderDefect
Doc/library/gzip.rst:108: WARNING: py:meth reference target not found: close
Doc/library/importlib.resources.rst:59: WARNING: py:class reference target not found: Anchor
Doc/library/xml.rst:73: WARNING: py:const reference target not found: pyexpat.EXPAT_VERSION

Plus a bit of extra cleanup, details in commits.

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

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

Direct use of the pyexpat module is deprecated, but this is how to check the version for security purposes

… in library/email.headerregistry.rst

…m.rst

On stdtypes.rst, set and frozenset are documented together and the frozenset has the working refs

willingc

Thanks @hugovk.

miss-islington-app · 2023-11-25T23:40:22Z

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

miss-islington-app · 2023-11-25T23:40:25Z

Sorry, @hugovk and @willingc, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 3faf8e586d36e73faba13d9b61663afed6a24cb4 3.12

miss-islington-app · 2023-11-25T23:40:38Z

Sorry, @hugovk and @willingc, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 3faf8e586d36e73faba13d9b61663afed6a24cb4 3.11

AlexWaygood · 2023-11-25T23:44:08Z

Doc/c-api/set.rst

@@ -147,7 +147,7 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.

   Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an
   error is encountered.  Does not raise :exc:`KeyError` for missing keys.  Raise a
-   :exc:`TypeError` if the *key* is unhashable.  Unlike the Python :meth:`~set.discard`
+   :exc:`TypeError` if the *key* is unhashable.  Unlike the Python :meth:`~frozenset.discard`


Ideally we'd fix it so that the original linked properly, given that frozensets don't have a .discard() method, but sets do 🙃

Good idea, although I'm not sure how to do it. PR welcome! 🙃

willingc · 2023-11-26T00:15:16Z

@hugovk or @AlexWaygood Would you mind doing the backports? I'm getting ready for a flight to Japan so will be offline for a while. Thanks!

hugovk · 2023-11-26T08:14:26Z

Yes, I'll take care of the backports. Enjoy your trip!

* Fix Sphinx warning in library/xml.rst Direct use of the pyexpat module is deprecated, but this is how to check the version for security purposes * Fix Sphinx warning in library/importlib.resources.rst * Use italics for parameters * Link to the exception * Fix Sphinx warning in library/gzip.rst * Document message and header defect base classes to fix Sphinx warning in library/email.headerregistry.rst * Restore feed_eof() doc to fix Sphinx warning in library/asyncio-stream.rst * Fix Sphinx warning in extending/newtypes.rst * Fix Sphinx warning in c-api/set.rst On stdtypes.rst, set and frozenset are documented together and the frozenset has the working refs (cherry picked from commit 3faf8e5) Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

bedevere-app · 2023-11-26T09:41:20Z

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

bedevere-app · 2023-11-26T09:55:50Z

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

* Fix Sphinx warning in library/xml.rst Direct use of the pyexpat module is deprecated, but this is how to check the version for security purposes * Fix Sphinx warning in library/importlib.resources.rst * Use italics for parameters * Link to the exception * Fix Sphinx warning in library/gzip.rst * Document message and header defect base classes to fix Sphinx warning in library/email.headerregistry.rst * Restore feed_eof() doc to fix Sphinx warning in library/asyncio-stream.rst * Fix Sphinx warning in extending/newtypes.rst * Fix Sphinx warning in c-api/set.rst On stdtypes.rst, set and frozenset are documented together and the frozenset has the working refs (cherry picked from commit 3faf8e5) Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

* Fix Sphinx warning in library/xml.rst Direct use of the pyexpat module is deprecated, but this is how to check the version for security purposes * Fix Sphinx warning in library/importlib.resources.rst * Use italics for parameters * Link to the exception * Fix Sphinx warning in library/gzip.rst * Document message and header defect base classes to fix Sphinx warning in library/email.headerregistry.rst * Restore feed_eof() doc to fix Sphinx warning in library/asyncio-stream.rst * Fix Sphinx warning in extending/newtypes.rst * Fix Sphinx warning in c-api/set.rst On stdtypes.rst, set and frozenset are documented together and the frozenset has the working refs

hugovk added 9 commits November 25, 2023 22:26

Fix Sphinx warning in library/xml.rst

e793c01

Direct use of the pyexpat module is deprecated, but this is how to check the version for security purposes

Fix Sphinx warning in library/importlib.resources.rst

7cd50ae

Use italics for parameters

da6503d

Link to the exception

8ab6552

Fix Sphinx warning in library/gzip.rst

d888ebf

Document message and header defect base classes to fix Sphinx warning…

e0e1ad3

… in library/email.headerregistry.rst

Restore feed_eof() doc to fix Sphinx warning in library/asyncio-strea…

add95f3

…m.rst

Fix Sphinx warning in extending/newtypes.rst

8dc76b8

Fix Sphinx warning in c-api/set.rst

6ba4afd

On stdtypes.rst, set and frozenset are documented together and the frozenset has the working refs

hugovk added docs Documentation in the Doc dir skip news needs backport to 3.11 only security fixes needs backport to 3.12 only security fixes labels Nov 25, 2023

bedevere-app bot mentioned this pull request Nov 25, 2023

Fix all Sphinx reference warnings in the documentation #101100

Open

hugovk marked this pull request as ready for review November 25, 2023 23:32

hugovk requested review from a team, brettcannon, ericsnowcurrently, ncoghlan, warsaw, 1st1, asvetlov, gvanrossum, kumaraditya303 and willingc as code owners November 25, 2023 23:32

bedevere-app bot added the awaiting core review label Nov 25, 2023

hugovk removed request for a team, brettcannon, warsaw and 1st1 November 25, 2023 23:32

hugovk removed request for ncoghlan, ericsnowcurrently, willingc, gvanrossum and kumaraditya303 November 25, 2023 23:32

willingc approved these changes Nov 25, 2023

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels Nov 25, 2023

willingc merged commit 3faf8e5 into python:main Nov 25, 2023

bedevere-app bot removed the awaiting merge label Nov 25, 2023

miss-islington-app bot assigned willingc Nov 25, 2023

AlexWaygood reviewed Nov 25, 2023

View reviewed changes

hugovk deleted the docs-fix-sphinx-warnings branch November 26, 2023 08:13

bedevere-app bot removed the needs backport to 3.12 only security fixes label Nov 26, 2023

bedevere-app bot removed the needs backport to 3.11 only security fixes label Nov 26, 2023

hugovk added a commit that referenced this pull request Nov 26, 2023

[3.11] gh-101100: Fix Sphinx reference warnings (GH-112416) (#112422)

fc657d0

hugovk added a commit that referenced this pull request Nov 26, 2023

[3.12] gh-101100: Fix Sphinx reference warnings (GH-112416) (#112420)

d7a7883

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

AlexWaygood mentioned this pull request Dec 5, 2023

gh-101100: Fix many easily solvable Sphinx nitpicks in the datamodel docs #112737

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-101100: Fix Sphinx reference warnings #112416

gh-101100: Fix Sphinx reference warnings #112416

hugovk commented Nov 25, 2023 •

edited by github-actions bot

Loading

willingc left a comment

miss-islington-app bot commented Nov 25, 2023

miss-islington-app bot commented Nov 25, 2023

miss-islington-app bot commented Nov 25, 2023

AlexWaygood Nov 25, 2023

hugovk Nov 26, 2023

willingc commented Nov 26, 2023 •

edited

Loading

hugovk commented Nov 26, 2023

bedevere-app bot commented Nov 26, 2023

bedevere-app bot commented Nov 26, 2023

gh-101100: Fix Sphinx reference warnings #112416

gh-101100: Fix Sphinx reference warnings #112416

Conversation

hugovk commented Nov 25, 2023 • edited by github-actions bot Loading

willingc left a comment

Choose a reason for hiding this comment

miss-islington-app bot commented Nov 25, 2023

miss-islington-app bot commented Nov 25, 2023

miss-islington-app bot commented Nov 25, 2023

AlexWaygood Nov 25, 2023

Choose a reason for hiding this comment

hugovk Nov 26, 2023

Choose a reason for hiding this comment

willingc commented Nov 26, 2023 • edited Loading

hugovk commented Nov 26, 2023

bedevere-app bot commented Nov 26, 2023

bedevere-app bot commented Nov 26, 2023

hugovk commented Nov 25, 2023 •

edited by github-actions bot

Loading

willingc commented Nov 26, 2023 •

edited

Loading