gh-107298: Fix yet more Sphinx warnings in the C API doc (GH-107345)

serhiy-storchaka · web-flow · commit 983305268e22 · 2023-07-27T18:44:32.000+03:00
diff --git a/Doc/c-api/capsule.rst b/Doc/c-api/capsule.rst
@@ -121,7 +121,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
    compared.)
 
    In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls to
-   any of the accessors (any function starting with :c:func:`PyCapsule_Get`) are
+   any of the accessors (any function starting with ``PyCapsule_Get``) are
    guaranteed to succeed.
 
    Return a nonzero value if the object is valid and matches the name passed in.
diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst
@@ -135,6 +135,8 @@ PyStatus
 
       Name of the function which created an error, can be ``NULL``.
 
+   .. c:namespace:: NULL
+
    Functions to create a status:
 
    .. c:function:: PyStatus PyStatus_Ok(void)
@@ -210,6 +212,8 @@ PyPreConfig
 
    Structure used to preinitialize Python.
 
+   .. c:namespace:: NULL
+
    Function to initialize a preconfiguration:
 
    .. c:function:: void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)
@@ -222,6 +226,8 @@ PyPreConfig
       Initialize the preconfiguration with :ref:`Isolated Configuration
       <init-isolated-conf>`.
 
+   .. c:namespace:: PyPreConfig
+
    Structure fields:
 
    .. c:member:: int allocator
@@ -429,6 +435,8 @@ PyConfig
    When done, the :c:func:`PyConfig_Clear` function must be used to release the
    configuration memory.
 
+   .. c:namespace:: NULL
+
    Structure methods:
 
    .. c:function:: void PyConfig_InitPythonConfig(PyConfig *config)
@@ -527,6 +535,8 @@ PyConfig
    The caller of these methods is responsible to handle exceptions (error or
    exit) using ``PyStatus_Exception()`` and ``Py_ExitStatusException()``.
 
+   .. c:namespace:: PyConfig
+
    Structure fields:
 
    .. c:member:: PyWideStringList argv
@@ -938,7 +948,7 @@ PyConfig
    .. c:member:: wchar_t* pythonpath_env
 
       Module search paths (:data:`sys.path`) as a string separated by ``DELIM``
-      (:data:`os.path.pathsep`).
+      (:data:`os.pathsep`).
 
       Set by the :envvar:`PYTHONPATH` environment variable.
 
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
@@ -616,7 +616,7 @@ and lose important information about the exact cause of the error.
 .. index:: single: sum_sequence()
 
 A simple example of detecting exceptions and passing them on is shown in the
-:c:func:`sum_sequence` example above.  It so happens that this example doesn't
+:c:func:`!sum_sequence` example above.  It so happens that this example doesn't
 need to clean up any owned references when it detects an error.  The following
 example function shows some error cleanup.  First, to remind you why you like
 Python, we show the equivalent Python code::
diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
@@ -431,6 +431,8 @@ Customize Memory Allocators
 
    Enum used to identify an allocator domain. Domains:
 
+   .. c:namespace:: NULL
+
    .. c:macro:: PYMEM_DOMAIN_RAW
 
       Functions:
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
@@ -119,7 +119,7 @@ Module Objects
    encoded to 'utf-8'.
 
    .. deprecated:: 3.2
-      :c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on
+      :c:func:`PyModule_GetFilename` raises :exc:`UnicodeEncodeError` on
       unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
 
 
diff --git a/Doc/c-api/none.rst b/Doc/c-api/none.rst
@@ -9,7 +9,7 @@ The ``None`` Object
 
 Note that the :c:type:`PyTypeObject` for ``None`` is not directly exposed in the
 Python/C API.  Since ``None`` is a singleton, testing for object identity (using
-``==`` in C) is sufficient. There is no :c:func:`PyNone_Check` function for the
+``==`` in C) is sufficient. There is no :c:func:`!PyNone_Check` function for the
 same reason.
 
 
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
@@ -293,7 +293,7 @@ Object Protocol
 
    Normally only class objects, i.e. instances of :class:`type` or a derived
    class, are considered classes.  However, objects can override this by having
-   a :attr:`__bases__` attribute (which must be a tuple of base classes).
+   a :attr:`~class.__bases__` attribute (which must be a tuple of base classes).
 
 
 .. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
@@ -310,10 +310,10 @@ Object Protocol
    is an instance of *cls* if its class is a subclass of *cls*.
 
    An instance *inst* can override what is considered its class by having a
-   :attr:`__class__` attribute.
+   :attr:`~instance.__class__` attribute.
 
    An object *cls* can override if it is considered a class, and what its base
-   classes are, by having a :attr:`__bases__` attribute (which must be a tuple
+   classes are, by having a :attr:`~class.__bases__` attribute (which must be a tuple
    of base classes).
 
 
diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst
@@ -110,7 +110,7 @@ or :class:`frozenset` or instances of their subtypes.
    .. index:: pair: built-in function; len
 
    Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
-   ``len(anyset)``.  Raises a :exc:`PyExc_SystemError` if *anyset* is not a
+   ``len(anyset)``.  Raises a :exc:`SystemError` if *anyset* is not a
    :class:`set`, :class:`frozenset`, or an instance of a subtype.
 
 
@@ -124,7 +124,7 @@ or :class:`frozenset` or instances of their subtypes.
    Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered.  Unlike
    the Python :meth:`~object.__contains__` method, this function does not automatically
    convert unhashable sets into temporary frozensets.  Raise a :exc:`TypeError` if
-   the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
+   the *key* is unhashable. Raise :exc:`SystemError` if *anyset* is not a
    :class:`set`, :class:`frozenset`, or an instance of a subtype.
 
 
@@ -149,7 +149,7 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
    error is encountered.  Does not raise :exc:`KeyError` for missing keys.  Raise a
    :exc:`TypeError` if the *key* is unhashable.  Unlike the Python :meth:`~set.discard`
    method, this function does not automatically convert unhashable sets into
-   temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is not an
+   temporary frozensets. Raise :exc:`SystemError` if *set* is not an
    instance of :class:`set` or its subtype.
 
 
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
@@ -167,7 +167,7 @@ Operating System Utilities
 
    .. versionchanged:: 3.8
       The function now uses the UTF-8 encoding on Windows if
-      :c:member:`PyConfig.legacy_windows_fs_encoding` is zero;
+      :c:member:`PyPreConfig.legacy_windows_fs_encoding` is zero;
 
 
 .. c:function:: char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)
@@ -209,7 +209,7 @@ Operating System Utilities
 
    .. versionchanged:: 3.8
       The function now uses the UTF-8 encoding on Windows if
-      :c:member:`PyConfig.legacy_windows_fs_encoding` is zero.
+      :c:member:`PyPreConfig.legacy_windows_fs_encoding` is zero.
 
 
 .. _systemfunctions:
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
@@ -103,7 +103,7 @@ Type Objects
    :c:func:`PyType_AddWatcher` will be called whenever
    :c:func:`PyType_Modified` reports a change to *type*. (The callback may be
    called only once for a series of consecutive modifications to *type*, if
-   :c:func:`PyType_Lookup` is not called on *type* between the modifications;
+   :c:func:`!_PyType_Lookup` is not called on *type* between the modifications;
    this is an implementation detail and subject to change.)
 
    An extension should never call ``PyType_Watch`` with a *watcher_id* that was
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
@@ -485,7 +485,7 @@ PyObject Slots
 --------------
 
 The type object structure extends the :c:type:`PyVarObject` structure. The
-:c:member:`~PyVarObject.ob_size` field is used for dynamic types (created by :func:`type_new`,
+:c:member:`~PyVarObject.ob_size` field is used for dynamic types (created by :c:func:`!type_new`,
 usually called from a class statement). Note that :c:data:`PyType_Type` (the
 metatype) initializes :c:member:`~PyTypeObject.tp_itemsize`, which means that its instances (i.e.
 type objects) *must* have the :c:member:`~PyVarObject.ob_size` field.
@@ -740,7 +740,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
       Before version 3.12, it was not recommended for
       :ref:`mutable heap types <heap-types>` to implement the vectorcall
       protocol.
-      When a user sets :attr:`~type.__call__` in Python code, only *tp_call* is
+      When a user sets :attr:`~object.__call__` in Python code, only *tp_call* is
       updated, likely making it inconsistent with the vectorcall function.
       Since 3.12, setting ``__call__`` will disable vectorcall optimization
       by clearing the :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag.
@@ -1369,8 +1369,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    The :c:member:`~PyTypeObject.tp_traverse` pointer is used by the garbage collector to detect
    reference cycles. A typical implementation of a :c:member:`~PyTypeObject.tp_traverse` function
    simply calls :c:func:`Py_VISIT` on each of the instance's members that are Python
-   objects that the instance owns. For example, this is function :c:func:`local_traverse` from the
-   :mod:`_thread` extension module::
+   objects that the instance owns. For example, this is function :c:func:`!local_traverse` from the
+   :mod:`!_thread` extension module::
 
       static int
       local_traverse(localobject *self, visitproc visit, void *arg)
@@ -1721,7 +1721,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    called; it may also be initialized to a dictionary containing initial attributes
    for the type.  Once :c:func:`PyType_Ready` has initialized the type, extra
    attributes for the type may be added to this dictionary only if they don't
-   correspond to overloaded operations (like :meth:`__add__`).  Once
+   correspond to overloaded operations (like :meth:`~object.__add__`).  Once
    initialization for the type has finished, this field should be
    treated as read-only.
 
@@ -1818,7 +1818,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    **Default:**
 
    This slot has no default.  For :ref:`static types <static-types>`, if the
-   field is ``NULL`` then no :attr:`__dict__` gets created for instances.
+   field is ``NULL`` then no :attr:`~object.__dict__` gets created for instances.
 
    If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the
    :c:member:`~PyTypeObject.tp_dict` field, then
@@ -1830,18 +1830,18 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
    An optional pointer to an instance initialization function.
 
-   This function corresponds to the :meth:`__init__` method of classes.  Like
-   :meth:`__init__`, it is possible to create an instance without calling
-   :meth:`__init__`, and it is possible to reinitialize an instance by calling its
-   :meth:`__init__` method again.
+   This function corresponds to the :meth:`~object.__init__` method of classes.  Like
+   :meth:`!__init__`, it is possible to create an instance without calling
+   :meth:`!__init__`, and it is possible to reinitialize an instance by calling its
+   :meth:`!__init__` method again.
 
    The function signature is::
 
       int tp_init(PyObject *self, PyObject *args, PyObject *kwds);
 
    The self argument is the instance to be initialized; the *args* and *kwds*
    arguments represent positional and keyword arguments of the call to
-   :meth:`__init__`.
+   :meth:`~object.__init__`.
 
    The :c:member:`~PyTypeObject.tp_init` function, if not ``NULL``, is called when an instance is
    created normally by calling its type, after the type's :c:member:`~PyTypeObject.tp_new` function
@@ -2130,7 +2130,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    In other words, it is used to implement
    :ref:`vectorcall <vectorcall>` for ``type.__call__``.
    If ``tp_vectorcall`` is ``NULL``, the default call implementation
-   using :attr:`__new__` and :attr:`__init__` is used.
+   using :meth:`~object.__new__` and :meth:`~object.__init__` is used.
 
    **Inheritance:**
 
@@ -2329,8 +2329,8 @@ Mapping Object Structures
 .. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript
 
    This function is used by :c:func:`PyObject_SetItem`,
-   :c:func:`PyObject_DelItem`, :c:func:`PyObject_SetSlice` and
-   :c:func:`PyObject_DelSlice`.  It has the same signature as
+   :c:func:`PyObject_DelItem`, :c:func:`PySequence_SetSlice` and
+   :c:func:`PySequence_DelSlice`.  It has the same signature as
    :c:func:`!PyObject_SetItem`, but *v* can also be set to ``NULL`` to delete
    an item.  If this slot is ``NULL``, the object does not support item
    assignment and deletion.
@@ -2552,7 +2552,7 @@ Async Object Structures
       PyObject *am_aiter(PyObject *self);
 
    Must return an :term:`asynchronous iterator` object.
-   See :meth:`__anext__` for details.
+   See :meth:`~object.__anext__` for details.
 
    This slot may be set to ``NULL`` if an object does not implement
    asynchronous iteration protocol.
@@ -2563,7 +2563,8 @@ Async Object Structures
 
       PyObject *am_anext(PyObject *self);
 
-   Must return an :term:`awaitable` object.  See :meth:`__anext__` for details.
+   Must return an :term:`awaitable` object.
+   See :meth:`~object.__anext__` for details.
    This slot may be set to ``NULL``.
 
 .. c:member:: sendfunc PyAsyncMethods.am_send
diff --git a/Doc/extending/embedding.rst b/Doc/extending/embedding.rst
@@ -269,7 +269,7 @@ following two statements before the call to :c:func:`Py_Initialize`::
    PyImport_AppendInittab("emb", &PyInit_emb);
 
 These two lines initialize the ``numargs`` variable, and make the
-:func:`emb.numargs` function accessible to the embedded Python interpreter.
+:func:`!emb.numargs` function accessible to the embedded Python interpreter.
 With these extensions, the Python script can do things like
 
 .. code-block:: python
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
@@ -197,7 +197,7 @@ The choice of which exception to raise is entirely yours.  There are predeclared
 C objects corresponding to all built-in Python exceptions, such as
 :c:data:`PyExc_ZeroDivisionError`, which you can use directly. Of course, you
 should choose exceptions wisely --- don't use :c:data:`PyExc_TypeError` to mean
-that a file couldn't be opened (that should probably be :c:data:`PyExc_IOError`).
+that a file couldn't be opened (that should probably be :c:data:`PyExc_OSError`).
 If something's wrong with the argument list, the :c:func:`PyArg_ParseTuple`
 function usually raises :c:data:`PyExc_TypeError`.  If you have an argument whose
 value must be in a particular range or must satisfy other conditions,
@@ -208,7 +208,7 @@ usually declare a static object variable at the beginning of your file::
 
    static PyObject *SpamError;
 
-and initialize it in your module's initialization function (:c:func:`PyInit_spam`)
+and initialize it in your module's initialization function (:c:func:`!PyInit_spam`)
 with an exception object::
 
    PyMODINIT_FUNC
@@ -354,7 +354,7 @@ The method table must be referenced in the module definition structure::
 
 This structure, in turn, must be passed to the interpreter in the module's
 initialization function.  The initialization function must be named
-:c:func:`PyInit_name`, where *name* is the name of the module, and should be the
+:c:func:`!PyInit_name`, where *name* is the name of the module, and should be the
 only non-\ ``static`` item defined in the module file::
 
    PyMODINIT_FUNC
@@ -368,7 +368,7 @@ declares any special linkage declarations required by the platform, and for C++
 declares the function as ``extern "C"``.
 
 When the Python program imports module :mod:`!spam` for the first time,
-:c:func:`PyInit_spam` is called. (See below for comments about embedding Python.)
+:c:func:`!PyInit_spam` is called. (See below for comments about embedding Python.)
 It calls :c:func:`PyModule_Create`, which returns a module object, and
 inserts built-in function objects into the newly created module based upon the
 table (an array of :c:type:`PyMethodDef` structures) found in the module definition.
@@ -378,7 +378,7 @@ certain errors, or return ``NULL`` if the module could not be initialized
 satisfactorily. The init function must return the module object to its caller,
 so that it then gets inserted into ``sys.modules``.
 
-When embedding Python, the :c:func:`PyInit_spam` function is not called
+When embedding Python, the :c:func:`!PyInit_spam` function is not called
 automatically unless there's an entry in the :c:data:`PyImport_Inittab` table.
 To add the module to the initialization table, use :c:func:`PyImport_AppendInittab`,
 optionally followed by an import of the module::
@@ -1220,13 +1220,13 @@ the module and retrieving its C API pointers; client modules only have to call
 this macro before accessing the C API.
 
 The exporting module is a modification of the :mod:`!spam` module from section
-:ref:`extending-simpleexample`. The function :func:`spam.system` does not call
+:ref:`extending-simpleexample`. The function :func:`!spam.system` does not call
 the C library function :c:func:`system` directly, but a function
-:c:func:`PySpam_System`, which would of course do something more complicated in
+:c:func:`!PySpam_System`, which would of course do something more complicated in
 reality (such as adding "spam" to every command). This function
-:c:func:`PySpam_System` is also exported to other extension modules.
+:c:func:`!PySpam_System` is also exported to other extension modules.
 
-The function :c:func:`PySpam_System` is a plain C function, declared
+The function :c:func:`!PySpam_System` is a plain C function, declared
 ``static`` like everything else::
 
    static int
@@ -1288,7 +1288,7 @@ function must take care of initializing the C API pointer array::
    }
 
 Note that ``PySpam_API`` is declared ``static``; otherwise the pointer
-array would disappear when :func:`PyInit_spam` terminates!
+array would disappear when :c:func:`!PyInit_spam` terminates!
 
 The bulk of the work is in the header file :file:`spammodule.h`, which looks
 like this::
@@ -1342,8 +1342,8 @@ like this::
    #endif /* !defined(Py_SPAMMODULE_H) */
 
 All that a client module must do in order to have access to the function
-:c:func:`PySpam_System` is to call the function (or rather macro)
-:c:func:`import_spam` in its initialization function::
+:c:func:`!PySpam_System` is to call the function (or rather macro)
+:c:func:`!import_spam` in its initialization function::
 
    PyMODINIT_FUNC
    PyInit_client(void)
diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst
diff --git a/Doc/howto/descriptor.rst b/Doc/howto/descriptor.rst
diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
