[3.11] bpo-46879: Fix incorrect sphinx object names in doc (GH-31615) #92974

miss-islington · 2022-05-19T15:35:13Z

API members documented in sphinx have an object name, which allow the
documentation to be linked from other projects. Sphinx calculates the
object name by prefixing the current module name to the directive
argument, e.g:

.. module:: foo
.. function:: bar.baz

becomes foo.bar.baz. Since these anchors aren't displayed in the
documentation, some mistakes have crept in, namely the Python stdlib
documentation currently contains the objects:

asyncio.asyncio.subprocess.DEVNULL
asyncio.asyncio.subprocess.PIPE
asyncio.asyncio.subprocess.STDOUT
asyncio.asyncio.subprocess.Process
multiprocessing.sharedctypes.multiprocessing.Manager
xml.etree.ElementTree.xml.etree.ElementInclude

This commit fixes this by making use of the :module: option which
without an argument makes sphinx take the directive argument as is
for the object name (avoiding the prefixing of the current module
name that led to these broken object names).

Co-authored-by: Łukasz Langa lukasz@langa.pl
(cherry picked from commit 2cdd57f)

Co-authored-by: Martin Fischer martin@push-f.com

API members documented in sphinx have an object name, which allow the documentation to be linked from other projects. Sphinx calculates the object name by prefixing the current module name to the directive argument, e.g: .. module:: foo .. function:: bar.baz becomes foo.bar.baz. Since these anchors aren't displayed in the documentation, some mistakes have crept in, namely the Python stdlib documentation currently contains the objects: * asyncio.asyncio.subprocess.DEVNULL * asyncio.asyncio.subprocess.PIPE * asyncio.asyncio.subprocess.STDOUT * asyncio.asyncio.subprocess.Process * multiprocessing.sharedctypes.multiprocessing.Manager * xml.etree.ElementTree.xml.etree.ElementInclude This commit fixes this by making use of the :module: option which without an argument makes sphinx take the directive argument as is for the object name (avoiding the prefixing of the current module name that led to these broken object names). Co-authored-by: Łukasz Langa <lukasz@langa.pl> (cherry picked from commit 2cdd57f) Co-authored-by: Martin Fischer <martin@push-f.com>

miss-islington · 2022-05-19T15:35:17Z