bpo-46879: Fix incorrect sphinx object names in doc (GH-31615)

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>
This commit is contained in:
Martin Fischer 2022-05-19 17:34:58 +02:00 committed by GitHub
parent 84b86000e2
commit 2cdd57f119
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 7 additions and 0 deletions

View File

@ -124,6 +124,7 @@ Constants
=========
.. data:: asyncio.subprocess.PIPE
:module:
Can be passed to the *stdin*, *stdout* or *stderr* parameters.
@ -137,11 +138,13 @@ Constants
attributes will point to :class:`StreamReader` instances.
.. data:: asyncio.subprocess.STDOUT
:module:
Special value that can be used as the *stderr* argument and indicates
that standard error should be redirected into standard output.
.. data:: asyncio.subprocess.DEVNULL
:module:
Special value that can be used as the *stdin*, *stdout* or *stderr* argument
to process creation functions. It indicates that the special file
@ -157,6 +160,7 @@ wrapper that allows communicating with subprocesses and watching for
their completion.
.. class:: asyncio.subprocess.Process
:module:
An object that wraps OS processes created by the
:func:`create_subprocess_exec` and :func:`create_subprocess_shell`

View File

@ -1666,6 +1666,7 @@ different machines. A manager object controls a server process which manages
proxies.
.. function:: multiprocessing.Manager()
:module:
Returns a started :class:`~multiprocessing.managers.SyncManager` object which
can be used for sharing objects between processes. The returned manager

View File

@ -826,6 +826,7 @@ Functions
^^^^^^^^^
.. function:: xml.etree.ElementInclude.default_loader( href, parse, encoding=None)
:module:
Default loader. This default loader reads an included resource from disk. *href* is a URL.
*parse* is for parse mode either "xml" or "text". *encoding*
@ -837,6 +838,7 @@ Functions
.. function:: xml.etree.ElementInclude.include( elem, loader=None, base_url=None, \
max_depth=6)
:module:
This function expands XInclude directives. *elem* is the root element. *loader* is
an optional resource loader. If omitted, it defaults to :func:`default_loader`.