[3.11] gh-101100: Sphinx warnings: pick the low hanging fruits (GH-10…

…7386) (GH-107418)

(cherry picked from commit f2d07d3)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

Doc/c-api/bool.rst

@@ -11,6 +11,12 @@ creation and deletion functions don't apply to booleans.  The following macros
 are available, however.
 
 
+.. c:var:: PyTypeObject PyBool_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python boolean type; it
+   is the same object as :class:`bool` in the Python layer.
+
+
 .. c:function:: int PyBool_Check(PyObject *o)
 
    Return true if *o* is of type :c:data:`PyBool_Type`.  This function always

Doc/faq/extending.rst

@@ -81,13 +81,13 @@ How do I extract C values from a Python object?
 
 That depends on the object's type.  If it's a tuple, :c:func:`PyTuple_Size`
 returns its length and :c:func:`PyTuple_GetItem` returns the item at a specified
-index.  Lists have similar functions, :c:func:`PyListSize` and
+index.  Lists have similar functions, :c:func:`PyList_Size` and
 :c:func:`PyList_GetItem`.
 
 For bytes, :c:func:`PyBytes_Size` returns its length and
 :c:func:`PyBytes_AsStringAndSize` provides a pointer to its value and its
 length.  Note that Python bytes objects may contain null bytes so C's
-:c:func:`strlen` should not be used.
+:c:func:`!strlen` should not be used.
 
 To test the type of an object, first make sure it isn't ``NULL``, and then use
 :c:func:`PyBytes_Check`, :c:func:`PyTuple_Check`, :c:func:`PyList_Check`, etc.

Doc/howto/curses.rst

@@ -527,7 +527,7 @@ If you're in doubt about the detailed behavior of the curses
 functions, consult the manual pages for your curses implementation,
 whether it's ncurses or a proprietary Unix vendor's.  The manual pages
 will document any quirks, and provide complete lists of all the
-functions, attributes, and :const:`ACS_\*` characters available to
+functions, attributes, and :ref:`ACS_\* <curses-acs-codes>` characters available to
 you.
 
 Because the curses API is so large, some functions aren't supported in

Doc/install/index.rst

@@ -774,7 +774,7 @@ Notes:
 
 (2)
    On Unix, if the :envvar:`HOME` environment variable is not defined, the user's
-   home directory will be determined with the :func:`getpwuid` function from the
+   home directory will be determined with the :func:`~pwd.getpwuid` function from the
    standard :mod:`pwd` module. This is done by the :func:`os.path.expanduser`
    function used by Distutils.
 

Doc/library/asyncio-extending.rst

@@ -69,7 +69,7 @@ Task lifetime support
 =====================
 
 A third party task implementation should call the following functions to keep a task
-visible by :func:`asyncio.get_tasks` and :func:`asyncio.current_task`:
+visible by :func:`asyncio.all_tasks` and :func:`asyncio.current_task`:
 
 .. function:: _register_task(task)
 

Doc/library/asyncio-future.rst

@@ -276,4 +276,4 @@ the Future has a result::
      :func:`concurrent.futures.as_completed` functions.
 
    - :meth:`asyncio.Future.cancel` accepts an optional ``msg`` argument,
-     but :func:`concurrent.futures.cancel` does not.
+     but :meth:`concurrent.futures.Future.cancel` does not.

Doc/library/bz2.rst

@@ -87,7 +87,8 @@ The :mod:`bz2` module contains:
    compressed streams.
 
    :class:`BZ2File` provides all of the members specified by the
-   :class:`io.BufferedIOBase`, except for :meth:`detach` and :meth:`truncate`.
+   :class:`io.BufferedIOBase`, except for :meth:`~io.BufferedIOBase.detach`
+   and :meth:`~io.IOBase.truncate`.
    Iteration and the :keyword:`with` statement are supported.
 
    :class:`BZ2File` also provides the following method:

Doc/library/code.rst

@@ -163,12 +163,12 @@ interpreter objects as well as the following additions.
 
    Push a line of source text to the interpreter. The line should not have a
    trailing newline; it may have internal newlines.  The line is appended to a
-   buffer and the interpreter's :meth:`runsource` method is called with the
+   buffer and the interpreter's :meth:`~InteractiveInterpreter.runsource` method is called with the
    concatenated contents of the buffer as source.  If this indicates that the
    command was executed or invalid, the buffer is reset; otherwise, the command is
    incomplete, and the buffer is left as it was after the line was appended.  The
    return value is ``True`` if more input is required, ``False`` if the line was
-   dealt with in some way (this is the same as :meth:`runsource`).
+   dealt with in some way (this is the same as :meth:`!runsource`).
 
 
 .. method:: InteractiveConsole.resetbuffer()

Doc/library/concurrent.rst

@@ -1,5 +1,5 @@
-The :mod:`concurrent` package
-=============================
+The :mod:`!concurrent` package
+==============================
 
 Currently, there is only one module in this package:
 

Doc/library/curses.rst

@@ -1651,6 +1651,8 @@ keys); also, the following keypad mappings are standard:
 | :kbd:`Page Down` | KEY_NPAGE |
 +------------------+-----------+
 
+.. _curses-acs-codes:
+
 The following table lists characters from the alternate character set. These are
 inherited from the VT100 terminal, and will generally be  available on software
 emulations such as X terminals.  When there is no graphic available, curses

Doc/library/email.charset.rst

@@ -150,7 +150,7 @@ Import this class from the :mod:`email.charset` module.
    .. method:: __str__()
 
       Returns *input_charset* as a string coerced to lower
-      case. :meth:`__repr__` is an alias for :meth:`__str__`.
+      case. :meth:`!__repr__` is an alias for :meth:`!__str__`.
 
 
    .. method:: __eq__(other)

Doc/library/email.encoders.rst

@@ -25,7 +25,7 @@ is especially true for :mimetype:`image/\*` and :mimetype:`text/\*` type message
 containing binary data.
 
 The :mod:`email` package provides some convenient encoders in its
-:mod:`encoders` module.  These encoders are actually used by the
+:mod:`~email.encoders` module.  These encoders are actually used by the
 :class:`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage`
 class constructors to provide default encodings.  All encoder functions take
 exactly one argument, the message object to encode.  They usually extract the

Doc/library/email.generator.rst

@@ -274,9 +274,9 @@ in with information about the part.
 .. rubric:: Footnotes
 
 .. [#] This statement assumes that you use the appropriate setting for
-       ``unixfrom``, and that there are no :mod:`policy` settings calling for
+       ``unixfrom``, and that there are no :mod:`email.policy` settings calling for
        automatic adjustments (for example,
-       :attr:`~email.policy.Policy.refold_source` must be ``none``, which is
+       :attr:`~email.policy.EmailPolicy.refold_source` must be ``none``, which is
        *not* the default).  It is also not 100% true, since if the message
        does not conform to the RFC standards occasionally information about the
        exact original text is lost during parsing error recovery.  It is a goal

Doc/library/email.message.rst

@@ -67,7 +67,7 @@ message objects.
       with the base :class:`~email.message.Message` class *maxheaderlen* is
       accepted, but defaults to ``None``, which means that by default the line
       length is controlled by the
-      :attr:`~email.policy.EmailPolicy.max_line_length` of the policy.  The
+      :attr:`~email.policy.Policy.max_line_length` of the policy.  The
       *policy* argument may be used to override the default policy obtained
       from the message instance.  This can be used to control some of the
       formatting produced by the method, since the specified *policy* will be
@@ -213,7 +213,7 @@ message objects.
          del msg['subject']
          msg['subject'] = 'Python roolz!'
 
-      If the :mod:`policy` defines certain headers to be unique (as the standard
+      If the :mod:`policy <email.policy>` defines certain headers to be unique (as the standard
       policies do), this method may raise a :exc:`ValueError` when an attempt
       is made to assign a value to such a header when one already exists.  This
       behavior is intentional for consistency's sake, but do not depend on it
@@ -378,7 +378,7 @@ message objects.
       deprecated.
 
       Note that existing parameter values of headers may be accessed through
-      the :attr:`~email.headerregistry.BaseHeader.params` attribute of the
+      the :attr:`~email.headerregistry.ParameterizedMIMEHeader.params` attribute of the
       header value (for example, ``msg['Content-Type'].params['charset']``).
 
       .. versionchanged:: 3.4 ``replace`` keyword was added.
@@ -691,7 +691,7 @@ message objects.
 
    .. method:: clear_content()
 
-      Remove the payload and all of the :exc:`Content-` headers, leaving
+      Remove the payload and all of the :mailheader:`!Content-` headers, leaving
       all other headers intact and in their original order.
 
 

Doc/library/email.parser.rst

@@ -39,9 +39,9 @@ returns the root object when you close the parser.
 Note that the parser can be extended in limited ways, and of course you can
 implement your own parser completely from scratch.  All of the logic that
 connects the :mod:`email` package's bundled parser and the
-:class:`~email.message.EmailMessage` class is embodied in the :mod:`policy`
+:class:`~email.message.EmailMessage` class is embodied in the :class:`~email.policy.Policy`
 class, so a custom parser can create message object trees any way it finds
-necessary by implementing custom versions of the appropriate :mod:`policy`
+necessary by implementing custom versions of the appropriate :class:`!Policy`
 methods.
 
 

Doc/library/filecmp.rst

@@ -100,7 +100,7 @@ The :class:`dircmp` class
    used to get various bits of information about the directory trees being
    compared.
 
-   Note that via :meth:`__getattr__` hooks, all attributes are computed lazily,
+   Note that via :meth:`~object.__getattr__` hooks, all attributes are computed lazily,
    so there is no speed penalty if only those attributes which are lightweight
    to compute are used.
 

Doc/library/fileinput.rst

@@ -177,7 +177,7 @@ available for subclassing as well:
       The keyword-only parameter *encoding* and *errors* are added.
 
    .. versionchanged:: 3.11
-      The ``'rU'`` and ``'U'`` modes and the :meth:`__getitem__` method have
+      The ``'rU'`` and ``'U'`` modes and the :meth:`!__getitem__` method have
       been removed.
 
 

Doc/library/graphlib.rst

@@ -115,7 +115,7 @@
       :meth:`TopologicalSorter.done` is less than the number that have been
       returned by :meth:`TopologicalSorter.get_ready`.
 
-      The :meth:`~TopologicalSorter.__bool__` method of this class defers to
+      The :meth:`~object.__bool__` method of this class defers to
       this function, so instead of::
 
           if ts.is_active():
@@ -204,7 +204,7 @@ The :mod:`graphlib` module defines the following exception classes:
    in the working graph. If multiple cycles exist, only one undefined choice among them will
    be reported and included in the exception.
 
-   The detected cycle can be accessed via the second element in the :attr:`~CycleError.args`
+   The detected cycle can be accessed via the second element in the :attr:`~BaseException.args`
    attribute of the exception instance and consists in a list of nodes, such that each node is,
    in the graph, an immediate predecessor of the next node in the list. In the reported list,
    the first and the last node will be the same, to make it clear that it is cyclic.

Doc/library/gzip.rst

@@ -70,7 +70,7 @@ The module defines the following items:
 .. class:: GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)
 
    Constructor for the :class:`GzipFile` class, which simulates most of the
-   methods of a :term:`file object`, with the exception of the :meth:`truncate`
+   methods of a :term:`file object`, with the exception of the :meth:`~io.IOBase.truncate`
    method.  At least one of *fileobj* and *filename* must be given a non-trivial
    value.
 
@@ -113,7 +113,7 @@ The module defines the following items:
 
    :class:`GzipFile` supports the :class:`io.BufferedIOBase` interface,
    including iteration and the :keyword:`with` statement.  Only the
-   :meth:`truncate` method isn't implemented.
+   :meth:`~io.IOBase.truncate` method isn't implemented.
 
    :class:`GzipFile` also provides the following method and attribute:
 

Doc/library/hashlib.rst

@@ -244,7 +244,7 @@ by the SHAKE algorithm.
 
 .. method:: shake.digest(length)
 
-   Return the digest of the data passed to the :meth:`update` method so far.
+   Return the digest of the data passed to the :meth:`~hash.update` method so far.
    This is a bytes object of size *length* which may contain bytes in
    the whole range from 0 to 255.
 
@@ -513,9 +513,9 @@ Simple hashing
 
 To calculate hash of some data, you should first construct a hash object by
 calling the appropriate constructor function (:func:`blake2b` or
-:func:`blake2s`), then update it with the data by calling :meth:`update` on the
+:func:`blake2s`), then update it with the data by calling :meth:`~hash.update` on the
 object, and, finally, get the digest out of the object by calling
-:meth:`digest` (or :meth:`hexdigest` for hex-encoded string).
+:meth:`~hash.digest` (or :meth:`~hash.hexdigest` for hex-encoded string).
 
     >>> from hashlib import blake2b
     >>> h = blake2b()

Doc/library/importlib.resources.abc.rst

@@ -139,10 +139,10 @@
 
     An abstract base class for resource readers capable of serving
     the :meth:`importlib.resources.files` interface. Subclasses
-    :class:`importlib.resources.abc.ResourceReader` and provides
-    concrete implementations of the :class:`importlib.resources.abc.ResourceReader`'s
+    :class:`ResourceReader` and provides
+    concrete implementations of the :class:`!ResourceReader`'s
     abstract methods. Therefore, any loader supplying
-    :class:`importlib.abc.TraversableResources` also supplies ResourceReader.
+    :class:`!TraversableResources` also supplies :class:`!ResourceReader`.
 
     Loaders that wish to support resource reading are expected to
     implement this interface.

Doc/library/json.rst

@@ -192,7 +192,7 @@ Basic Usage
    dictionaries will be sorted by key.
 
    To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the
-   :meth:`default` method to serialize additional types), specify it with the
+   :meth:`~JSONEncoder.default` method to serialize additional types), specify it with the
    *cls* kwarg; otherwise :class:`JSONEncoder` is used.
 
    .. versionchanged:: 3.6
@@ -422,7 +422,7 @@ Encoders and Decoders
       Added support for int- and float-derived Enum classes.
 
    To extend this to recognize other objects, subclass and implement a
-   :meth:`default` method with another method that returns a serializable object
+   :meth:`~JSONEncoder.default` method with another method that returns a serializable object
    for ``o`` if possible, otherwise it should call the superclass implementation
    (to raise :exc:`TypeError`).
 
@@ -483,7 +483,7 @@ Encoders and Decoders
       :exc:`TypeError`).
 
       For example, to support arbitrary iterators, you could implement
-      :meth:`default` like this::
+      :meth:`~JSONEncoder.default` like this::
 
          def default(self, o):
             try:

Doc/library/logging.rst

@@ -385,21 +385,21 @@ have specific values relative to the predefined levels. If you define a level
 with the same numeric value, it overwrites the predefined value; the predefined
 name is lost.
 
-+--------------+---------------+
-| Level        | Numeric value |
-+==============+===============+
-| ``CRITICAL`` | 50            |
-+--------------+---------------+
-| ``ERROR``    | 40            |
-+--------------+---------------+
-| ``WARNING``  | 30            |
-+--------------+---------------+
-| ``INFO``     | 20            |
-+--------------+---------------+
-| ``DEBUG``    | 10            |
-+--------------+---------------+
-| ``NOTSET``   | 0             |
-+--------------+---------------+
++-----------------------+---------------+
+| Level                 | Numeric value |
++=======================+===============+
+| .. py:data:: CRITICAL | 50            |
++-----------------------+---------------+
+| .. py:data:: ERROR    | 40            |
++-----------------------+---------------+
+| .. py:data:: WARNING  | 30            |
++-----------------------+---------------+
+| .. py:data:: INFO     | 20            |
++-----------------------+---------------+
+| .. py:data:: DEBUG    | 10            |
++-----------------------+---------------+
+| .. py:data:: NOTSET   | 0             |
++-----------------------+---------------+
 
 
 .. _handler:

Doc/library/lzma.rst

@@ -100,7 +100,8 @@ Reading and writing compressed files
    *filters* arguments have the same meanings as for :class:`LZMACompressor`.
 
    :class:`LZMAFile` supports all the members specified by
-   :class:`io.BufferedIOBase`, except for :meth:`detach` and :meth:`truncate`.
+   :class:`io.BufferedIOBase`, except for :meth:`~io.BufferedIOBase.detach`
+   and :meth:`~io.IOBase.truncate`.
    Iteration and the :keyword:`with` statement are supported.
 
    The following method is also provided:

Doc/library/msvcrt.rst

@@ -38,7 +38,7 @@ File Operations
    Lock part of a file based on file descriptor *fd* from the C runtime.  Raises
    :exc:`OSError` on failure.  The locked region of the file extends from the
    current file position for *nbytes* bytes, and may continue beyond the end of the
-   file.  *mode* must be one of the :const:`LK_\*` constants listed below. Multiple
+   file.  *mode* must be one of the :const:`!LK_\*` constants listed below. Multiple
    regions in a file may be locked at the same time, but may not overlap.  Adjacent
    regions are not merged; they must be unlocked individually.
 

Doc/library/netrc.rst

@@ -51,9 +51,19 @@ the Unix :program:`ftp` program and other FTP clients.
 
    Exception raised by the :class:`~netrc.netrc` class when syntactical errors are
    encountered in source text.  Instances of this exception provide three
-   interesting attributes:  :attr:`msg` is a textual explanation of the error,
-   :attr:`filename` is the name of the source file, and :attr:`lineno` gives the
-   line number on which the error was found.
+   interesting attributes:
+
+   .. attribute:: msg
+
+      Textual explanation of the error.
+
+   .. attribute:: filename
+
+      The name of the source file.
+
+   .. attribute:: lineno
+
+      The line number on which the error was found.
 
 
 .. _netrc-objects:

Doc/library/operator.rst

@@ -59,9 +59,9 @@ truth tests, identity tests, and boolean operations:
               __not__(obj)
 
    Return the outcome of :keyword:`not` *obj*.  (Note that there is no
-   :meth:`__not__` method for object instances; only the interpreter core defines
-   this operation.  The result is affected by the :meth:`__bool__` and
-   :meth:`__len__` methods.)
+   :meth:`!__not__` method for object instances; only the interpreter core defines
+   this operation.  The result is affected by the :meth:`~object.__bool__` and
+   :meth:`~object.__len__` methods.)
 
 
 .. function:: truth(obj)

Doc/library/poplib.rst

@@ -156,7 +156,7 @@ A :class:`POP3` instance has the following methods:
 .. method:: POP3.pass_(password)
 
    Send password, response includes message count and mailbox size. Note: the
-   mailbox on the server is locked until :meth:`~poplib.quit` is called.
+   mailbox on the server is locked until :meth:`~POP3.quit` is called.
 
 
 .. method:: POP3.apop(user, secret)