[3.12] gh-101100: Fix Sphinx warning in references with asterisks (GH-113029) (#113043)

gh-101100: Fix Sphinx warning in references with asterisks (GH-113029)
(cherry picked from commit 3531ea4)

Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>

Author: 3 people

Doc/library/bdb.rst

@@ -294,7 +294,7 @@ The :mod:`bdb` module also defines two classes:
    .. method:: set_quit()
 
       Set the :attr:`quitting` attribute to ``True``.  This raises :exc:`BdbQuit` in
-      the next call to one of the :meth:`dispatch_\*` methods.
+      the next call to one of the :meth:`!dispatch_\*` methods.
 
 
    Derived classes and clients can call the following methods to manipulate

Doc/library/cmd.rst

@@ -73,7 +73,7 @@ A :class:`Cmd` instance has the following methods:
 
    This method will return when the :meth:`postcmd` method returns a true value.
    The *stop* argument to :meth:`postcmd` is the return value from the command's
-   corresponding :meth:`do_\*` method.
+   corresponding :meth:`!do_\*` method.
 
    If completion is enabled, completing commands will be done automatically, and
    completing of commands args is done by calling :meth:`complete_foo` with
@@ -88,7 +88,7 @@ A :class:`Cmd` instance has the following methods:
    :meth:`help_bar`, and if that is not present, prints the docstring of
    :meth:`do_bar`, if available.  With no argument, :meth:`do_help` lists all
    available help topics (that is, all commands with corresponding
-   :meth:`help_\*` methods or commands that have docstrings), and also lists any
+   :meth:`!help_\*` methods or commands that have docstrings), and also lists any
    undocumented commands.
 
 
@@ -98,7 +98,7 @@ A :class:`Cmd` instance has the following methods:
    This may be overridden, but should not normally need to be; see the
    :meth:`precmd` and :meth:`postcmd` methods for useful execution hooks.  The
    return value is a flag indicating whether interpretation of commands by the
-   interpreter should stop.  If there is a :meth:`do_\*` method for the command
+   interpreter should stop.  If there is a :meth:`!do_\*` method for the command
    *str*, the return value of that method is returned, otherwise the return value
    from the :meth:`default` method is returned.
 
@@ -118,7 +118,7 @@ A :class:`Cmd` instance has the following methods:
 .. method:: Cmd.completedefault(text, line, begidx, endidx)
 
    Method called to complete an input line when no command-specific
-   :meth:`complete_\*` method is available.  By default, it returns an empty list.
+   :meth:`!complete_\*` method is available.  By default, it returns an empty list.
 
 
 .. method:: Cmd.columnize(list, displaywidth=80)
@@ -199,14 +199,14 @@ Instances of :class:`Cmd` subclasses have some public instance variables:
 .. attribute:: Cmd.misc_header
 
    The header to issue if the help output has a section for miscellaneous  help
-   topics (that is, there are :meth:`help_\*` methods without corresponding
-   :meth:`do_\*` methods).
+   topics (that is, there are :meth:`!help_\*` methods without corresponding
+   :meth:`!do_\*` methods).
 
 
 .. attribute:: Cmd.undoc_header
 
    The header to issue if the help output has a section for undocumented  commands
-   (that is, there are :meth:`do_\*` methods without corresponding :meth:`help_\*`
+   (that is, there are :meth:`!do_\*` methods without corresponding :meth:`!help_\*`
    methods).
 
 

Doc/library/configparser.rst

@@ -955,7 +955,7 @@ ConfigParser Objects
    When *converters* is given, it should be a dictionary where each key
    represents the name of a type converter and each value is a callable
    implementing the conversion from string to the desired datatype.  Every
-   converter gets its own corresponding :meth:`get*()` method on the parser
+   converter gets its own corresponding :meth:`!get*()` method on the parser
    object and section proxies.
 
    .. versionchanged:: 3.1

Doc/library/csv.rst

@@ -309,6 +309,8 @@ An example for :class:`Sniffer` use::
        # ... process CSV file contents here ...
 
 
+.. _csv-constants:
+
 The :mod:`csv` module defines the following constants:
 
 .. data:: QUOTE_ALL
@@ -432,8 +434,8 @@ Dialects support the following attributes:
 .. attribute:: Dialect.quoting
 
    Controls when quotes should be generated by the writer and recognised by the
-   reader.  It can take on any of the :const:`QUOTE_\*` constants (see section
-   :ref:`csv-contents`) and defaults to :const:`QUOTE_MINIMAL`.
+   reader.  It can take on any of the :ref:`QUOTE_\* constants <csv-constants>`
+   and defaults to :const:`QUOTE_MINIMAL`.
 
 
 .. attribute:: Dialect.skipinitialspace

Doc/library/http.server.rst

@@ -65,10 +65,10 @@ provides three different variants:
 
    The handler will parse the request and the headers, then call a method
    specific to the request type. The method name is constructed from the
-   request. For example, for the request method ``SPAM``, the :meth:`do_SPAM`
+   request. For example, for the request method ``SPAM``, the :meth:`!do_SPAM`
    method will be called with no arguments. All of the relevant information is
    stored in instance variables of the handler.  Subclasses should not need to
-   override or extend the :meth:`__init__` method.
+   override or extend the :meth:`!__init__` method.
 
    :class:`BaseHTTPRequestHandler` has the following instance variables:
 
@@ -187,13 +187,13 @@ provides three different variants:
 
       Calls :meth:`handle_one_request` once (or, if persistent connections are
       enabled, multiple times) to handle incoming HTTP requests. You should
-      never need to override it; instead, implement appropriate :meth:`do_\*`
+      never need to override it; instead, implement appropriate :meth:`!do_\*`
       methods.
 
    .. method:: handle_one_request()
 
       This method will parse and dispatch the request to the appropriate
-      :meth:`do_\*` method.  You should never need to override it.
+      :meth:`!do_\*` method.  You should never need to override it.
 
    .. method:: handle_expect_100()
 

Doc/library/locale.rst

@@ -309,7 +309,7 @@ The :mod:`locale` module defines the following exception and functions:
 .. function:: getlocale(category=LC_CTYPE)
 
    Returns the current setting for the given locale category as sequence containing
-   *language code*, *encoding*. *category* may be one of the :const:`LC_\*` values
+   *language code*, *encoding*. *category* may be one of the :const:`!LC_\*` values
    except :const:`LC_ALL`.  It defaults to :const:`LC_CTYPE`.
 
    Except for the code ``'C'``, the language code corresponds to :rfc:`1766`.

Doc/library/os.rst

@@ -3959,7 +3959,7 @@ to be ignored.
    The "l" and "v" variants of the :func:`exec\* <execl>` functions differ in how
    command-line arguments are passed.  The "l" variants are perhaps the easiest
    to work with if the number of parameters is fixed when the code is written; the
-   individual parameters simply become additional parameters to the :func:`execl\*`
+   individual parameters simply become additional parameters to the :func:`!execl\*`
    functions.  The "v" variants are good when the number of parameters is
    variable, with the arguments being passed in a list or tuple as the *args*
    parameter.  In either case, the arguments to the child process should start with
@@ -4497,7 +4497,7 @@ written in Python, such as a mail server's external command delivery program.
    command-line arguments are passed.  The "l" variants are perhaps the easiest
    to work with if the number of parameters is fixed when the code is written; the
    individual parameters simply become additional parameters to the
-   :func:`spawnl\*` functions.  The "v" variants are good when the number of
+   :func:`!spawnl\*` functions.  The "v" variants are good when the number of
    parameters is variable, with the arguments being passed in a list or tuple as
    the *args* parameter.  In either case, the arguments to the child process must
    start with the name of the command being run.
@@ -4547,7 +4547,7 @@ written in Python, such as a mail server's external command delivery program.
           P_NOWAITO
 
    Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` family of
-   functions.  If either of these values is given, the :func:`spawn\*` functions
+   functions.  If either of these values is given, the :func:`spawn\* <spawnl>` functions
    will return as soon as the new process has been created, with the process id as
    the return value.
 
@@ -4557,7 +4557,7 @@ written in Python, such as a mail server's external command delivery program.
 .. data:: P_WAIT
 
    Possible value for the *mode* parameter to the :func:`spawn\* <spawnl>` family of
-   functions.  If this is given as *mode*, the :func:`spawn\*` functions will not
+   functions.  If this is given as *mode*, the :func:`spawn\* <spawnl>` functions will not
    return until the new process has run to completion and will return the exit code
    of the process the run is successful, or ``-signal`` if a signal kills the
    process.

Doc/library/resource.rst

@@ -277,7 +277,7 @@ These functions are used to retrieve resource usage information:
 
    This function returns an object that describes the resources consumed by either
    the current process or its children, as specified by the *who* parameter.  The
-   *who* parameter should be specified using one of the :const:`RUSAGE_\*`
+   *who* parameter should be specified using one of the :const:`!RUSAGE_\*`
    constants described below.
 
    A simple example::
@@ -353,7 +353,7 @@ These functions are used to retrieve resource usage information:
    Returns the number of bytes in a system page. (This need not be the same as the
    hardware page size.)
 
-The following :const:`RUSAGE_\*` symbols are passed to the :func:`getrusage`
+The following :const:`!RUSAGE_\*` symbols are passed to the :func:`getrusage`
 function to specify which processes information should be provided for.
 
 

Doc/library/socket.rst

@@ -311,7 +311,7 @@ Exceptions
    The accompanying value is a pair ``(error, string)`` representing an error
    returned by a library call.  *string* represents the description of
    *error*, as returned by the :c:func:`gai_strerror` C function.  The
-   numeric *error* value will match one of the :const:`EAI_\*` constants
+   numeric *error* value will match one of the :const:`!EAI_\*` constants
    defined in this module.
 
    .. versionchanged:: 3.3
@@ -1517,7 +1517,7 @@ to sockets.
 .. method:: socket.getsockopt(level, optname[, buflen])
 
    Return the value of the given socket option (see the Unix man page
-   :manpage:`getsockopt(2)`).  The needed symbolic constants (:const:`SO_\*` etc.)
+   :manpage:`getsockopt(2)`).  The needed symbolic constants (:ref:`SO_\* etc. <socket-unix-constants>`)
    are defined in this module.  If *buflen* is absent, an integer option is assumed
    and its integer value is returned by the function.  If *buflen* is present, it
    specifies the maximum length of the buffer used to receive the option in, and
@@ -1937,8 +1937,8 @@ to sockets.
    .. index:: pair: module; struct
 
    Set the value of the given socket option (see the Unix manual page
-   :manpage:`setsockopt(2)`).  The needed symbolic constants are defined in the
-   :mod:`socket` module (:const:`SO_\*` etc.).  The value can be an integer,
+   :manpage:`setsockopt(2)`).  The needed symbolic constants are defined in this
+   module (:ref:`!SO_\* etc. <socket-unix-constants>`).  The value can be an integer,
    ``None`` or a :term:`bytes-like object` representing a buffer. In the later
    case it is up to the caller to ensure that the bytestring contains the
    proper bits (see the optional built-in module :mod:`struct` for a way to

Doc/library/unittest.rst

@@ -390,8 +390,8 @@ testing code::
            widget = Widget('The widget')
            self.assertEqual(widget.size(), (50, 50))
 
-Note that in order to test something, we use one of the :meth:`assert\*`
-methods provided by the :class:`TestCase` base class.  If the test fails, an
+Note that in order to test something, we use one of the :ref:`assert\* methods <assert-methods>`
+provided by the :class:`TestCase` base class.  If the test fails, an
 exception will be raised with an explanatory message, and :mod:`unittest`
 will identify the test case as a :dfn:`failure`.  Any other exceptions will be
 treated as :dfn:`errors`.
@@ -1932,14 +1932,14 @@ Loading and running tests
       String giving the prefix of method names which will be interpreted as test
       methods.  The default value is ``'test'``.
 
-      This affects :meth:`getTestCaseNames` and all the :meth:`loadTestsFrom\*`
+      This affects :meth:`getTestCaseNames` and all the ``loadTestsFrom*``
       methods.
 
 
    .. attribute:: sortTestMethodsUsing
 
       Function to be used to compare method names when sorting them in
-      :meth:`getTestCaseNames` and all the :meth:`loadTestsFrom\*` methods.
+      :meth:`getTestCaseNames` and all the ``loadTestsFrom*`` methods.
 
 
    .. attribute:: suiteClass
@@ -1948,7 +1948,7 @@ Loading and running tests
       methods on the resulting object are needed.  The default value is the
       :class:`TestSuite` class.
 
-      This affects all the :meth:`loadTestsFrom\*` methods.
+      This affects all the ``loadTestsFrom*`` methods.
 
    .. attribute:: testNamePatterns
 
@@ -1961,7 +1961,7 @@ Loading and running tests
       so unlike patterns passed to the ``-k`` option, simple substring patterns
       will have to be converted using ``*`` wildcards.
 
-      This affects all the :meth:`loadTestsFrom\*` methods.
+      This affects all the ``loadTestsFrom*`` methods.
 
       .. versionadded:: 3.7
 
@@ -1995,7 +1995,7 @@ Loading and running tests
 
       A list containing 2-tuples of :class:`TestCase` instances and strings
       holding formatted tracebacks. Each tuple represents a test where a failure
-      was explicitly signalled using the :meth:`TestCase.assert\*` methods.
+      was explicitly signalled using the :ref:`assert\* methods <assert-methods>`.
 
    .. attribute:: skipped
 

Doc/library/urllib.request.rst

@@ -723,8 +723,8 @@ The following attribute and methods should only be used by classes derived from
 .. note::
 
    The convention has been adopted that subclasses defining
-   :meth:`<protocol>_request` or :meth:`<protocol>_response` methods are named
-   :class:`\*Processor`; all others are named :class:`\*Handler`.
+   :meth:`!<protocol>_request` or :meth:`!<protocol>_response` methods are named
+   :class:`!\*Processor`; all others are named :class:`!\*Handler`.
 
 
 .. attribute:: BaseHandler.parent
@@ -844,9 +844,9 @@ HTTPRedirectHandler Objects
 .. method:: HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)
 
    Return a :class:`Request` or ``None`` in response to a redirect. This is called
-   by the default implementations of the :meth:`http_error_30\*` methods when a
+   by the default implementations of the :meth:`!http_error_30\*` methods when a
    redirection is received from the server.  If a redirection should take place,
-   return a new :class:`Request` to allow :meth:`http_error_30\*` to perform the
+   return a new :class:`Request` to allow :meth:`!http_error_30\*` to perform the
    redirect to *newurl*.  Otherwise, raise :exc:`~urllib.error.HTTPError` if
    no other handler should try to handle this URL, or return ``None`` if you
    can't but another handler might.

Doc/library/xml.dom.rst

@@ -734,7 +734,7 @@ NamedNodeMap Objects
    attribute node.  Get its value with the :attr:`value` attribute.
 
 There are also experimental methods that give this class more mapping behavior.
-You can use them or you can use the standardized :meth:`getAttribute\*` family
+You can use them or you can use the standardized :meth:`!getAttribute\*` family
 of methods on the :class:`Element` objects.
 
 

Doc/whatsnew/2.3.rst

@@ -1362,7 +1362,7 @@ complete list of changes, or look through the CVS logs for all the details.
   :mod:`os` module. (Contributed by Gustavo Niemeyer, Geert Jansen, and Denis S.
   Otkidach.)
 
-* In the :mod:`os` module, the :func:`\*stat` family of functions can now report
+* In the :mod:`os` module, the :func:`!\*stat` family of functions can now report
   fractions of a second in a timestamp.  Such time stamps are represented as
   floats, similar to the value returned by :func:`time.time`.
 

Doc/whatsnew/2.4.rst

@@ -1164,7 +1164,7 @@ complete list of changes, or look through the CVS logs for all the details.
 
 * A number of functions were added to the :mod:`locale`  module, such as
   :func:`bind_textdomain_codeset` to specify a particular encoding and a family of
-  :func:`l\*gettext` functions that return messages in the chosen encoding.
+  :func:`!l\*gettext` functions that return messages in the chosen encoding.
   (Contributed by Gustavo Niemeyer.)
 
 * Some keyword arguments were added to the :mod:`logging` package's

Doc/whatsnew/2.5.rst

@@ -1167,10 +1167,10 @@ marked in the following list.
 
 * It's now illegal to mix iterating over a file  with ``for line in file`` and
   calling  the file object's :meth:`read`/:meth:`readline`/:meth:`readlines`
-  methods.  Iteration uses an internal buffer and the  :meth:`read\*` methods
+  methods.  Iteration uses an internal buffer and the  :meth:`!read\*` methods
   don't use that buffer.   Instead they would return the data following the
   buffer, causing the data to appear out of order.  Mixing iteration and these
-  methods will now trigger a :exc:`ValueError` from the :meth:`read\*` method.
+  methods will now trigger a :exc:`ValueError` from the :meth:`!read\*` method.
   (Implemented by Thomas Wouters.)
 
   .. Patch 1397960

Doc/whatsnew/2.7.rst

@@ -1417,7 +1417,7 @@ changes, or look through the Subversion logs for all the details.
   :func:`~math.lgamma` for the natural log of the Gamma function.
   (Contributed by Mark Dickinson and nirinA raseliarison; :issue:`3366`.)
 
-* The :mod:`multiprocessing` module's :class:`Manager*` classes
+* The :mod:`multiprocessing` module's :class:`!Manager*` classes
   can now be passed a callable that will be called whenever
   a subprocess is started, along with a set of arguments that will be
   passed to the callable.

Doc/whatsnew/3.4.rst

@@ -1936,7 +1936,7 @@ Other Improvements
 * The :ref:`python <using-on-cmdline>` command has a new :ref:`option
   <using-on-misc-options>`, ``-I``, which causes it to run in "isolated mode",
   which means that :data:`sys.path` contains neither the script's directory nor
-  the user's ``site-packages`` directory, and all :envvar:`PYTHON*` environment
+  the user's ``site-packages`` directory, and all :envvar:`!PYTHON*` environment
   variables are ignored (it implies both ``-s`` and ``-E``).  Other
   restrictions may also be applied in the future, with the goal being to
   isolate the execution of a script from the user's environment.  This is

Misc/NEWS.d/3.10.0a1.rst

@@ -605,8 +605,8 @@ Opt out serialization/deserialization for _random.Random
 .. nonce: jxJ4yn
 .. section: Core and Builtins
 
-Rename `PyPegen*` functions to `PyParser*`, so that we can remove the old
-set of `PyParser*` functions that were using the old parser, but keep
+Rename ``PyPegen*`` functions to ``PyParser*``, so that we can remove the old
+set of ``PyParser*`` functions that were using the old parser, but keep
 everything backwards-compatible.
 
 ..

Misc/NEWS.d/3.12.0a1.rst

@@ -1913,7 +1913,7 @@ Stinner.
 .. nonce: Uxc9al
 .. section: Library
 
-Allow :mod:`venv` to pass along :envvar:`PYTHON*` variables to ``ensurepip``
+Allow :mod:`venv` to pass along :envvar:`!PYTHON*` variables to ``ensurepip``
 and ``pip`` when they do not impact path resolution
 
 ..

Misc/NEWS.d/3.12.0b1.rst

@@ -880,7 +880,7 @@ Update the ``repr`` of :class:`typing.Unpack` according to :pep:`692`.
 .. section: Library
 
 Make :mod:`dis` display the names of the args for
-:opcode:`CALL_INTRINSIC_*`.
+:opcode:`!CALL_INTRINSIC_*`.
 
 ..
 

Misc/NEWS.d/3.6.0a2.rst

@@ -603,7 +603,7 @@ configuring text widget colors to a new function.
 .. nonce: RbyFuV
 .. section: IDLE
 
-Rename many `idlelib/*.py` and `idle_test/test_*.py` files. Edit files to
+Rename many ``idlelib/*.py`` and ``idle_test/test_*.py`` files. Edit files to
 replace old names with new names when the old name referred to the module
 rather than the class it contained. See the issue and IDLE section in What's
 New in 3.6 for more.