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>

diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
index e5000532a895dd104e4c5d5e6e7705f90210cbc5..28d0b21e8180b64d022c7add1e76a6c611fbc158 100644 (file)
--- a/Doc/library/asyncio-subprocess.rst
+++ b/Doc/library/asyncio-subprocess.rst
@@ -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`

diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 70802ee1fdecb90fd5ab5479df0bc382b7aa160e..2a66b0f65c0882466db932733a1e0e74d5d2c707 100644 (file)
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -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

diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index e3932bc9e659fe3441cc5ebe10853b2b44a60570..2fe0d2e082fb3a011b637a4e0521d8c5ad48c898 100644 (file)
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -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`.