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

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

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)

Doc/extending/newtypes.rst

@@ -286,9 +286,9 @@ be read-only or read-write.  The structures in the table are defined as::
 
 For each entry in the table, a :term:`descriptor` will be constructed and added to the
 type which will be able to extract a value from the instance structure.  The
-:attr:`type` field should contain a type code like :c:macro:`Py_T_INT` or
+:c:member:`~PyMemberDef.type` field should contain a type code like :c:macro:`Py_T_INT` or
 :c:macro:`Py_T_DOUBLE`; the value will be used to determine how to
-convert Python values to and from C values.  The :attr:`flags` field is used to
+convert Python values to and from C values.  The :c:member:`~PyMemberDef.flags` field is used to
 store flags which control how the attribute can be accessed: you can set it to
 :c:macro:`Py_READONLY` to prevent Python code from setting it.
 
@@ -298,7 +298,7 @@ have an associated doc string simply by providing the text in the table.  An
 application can use the introspection API to retrieve the descriptor from the
 class object, and get the doc string using its :attr:`__doc__` attribute.
 
-As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :attr:`name` value
+As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.name` value
 of ``NULL`` is required.
 
 .. XXX Descriptors need to be explained in more detail somewhere, but not here.
@@ -323,7 +323,7 @@ called, so that if you do need to extend their functionality, you'll understand
 what needs to be done.
 
 The :c:member:`~PyTypeObject.tp_getattr` handler is called when the object requires an attribute
-look-up.  It is called in the same situations where the :meth:`__getattr__`
+look-up.  It is called in the same situations where the :meth:`~object.__getattr__`
 method of a class would be called.
 
 Here is an example::
@@ -342,8 +342,8 @@ Here is an example::
        return NULL;
    }
 
-The :c:member:`~PyTypeObject.tp_setattr` handler is called when the :meth:`__setattr__` or
-:meth:`__delattr__` method of a class instance would be called.  When an
+The :c:member:`~PyTypeObject.tp_setattr` handler is called when the :meth:`~object.__setattr__` or
+:meth:`~object.__delattr__` method of a class instance would be called.  When an
 attribute should be deleted, the third parameter will be ``NULL``.  Here is an
 example that simply raises an exception; if this were really all you wanted, the
 :c:member:`~PyTypeObject.tp_setattr` handler should be set to ``NULL``. ::
@@ -364,7 +364,7 @@ Object Comparison
 
 The :c:member:`~PyTypeObject.tp_richcompare` handler is called when comparisons are needed.  It is
 analogous to the :ref:`rich comparison methods <richcmpfuncs>`, like
-:meth:`__lt__`, and also called by :c:func:`PyObject_RichCompare` and
+:meth:`!__lt__`, and also called by :c:func:`PyObject_RichCompare` and
 :c:func:`PyObject_RichCompareBool`.
 
 This function is called with two Python objects and the operator as arguments,
@@ -505,7 +505,7 @@ These functions provide support for the iterator protocol.  Both handlers
 take exactly one parameter, the instance for which they are being called,
 and return a new reference.  In the case of an error, they should set an
 exception and return ``NULL``.  :c:member:`~PyTypeObject.tp_iter` corresponds
-to the Python :meth:`__iter__` method, while :c:member:`~PyTypeObject.tp_iternext`
+to the Python :meth:`~object.__iter__` method, while :c:member:`~PyTypeObject.tp_iternext`
 corresponds to the Python :meth:`~iterator.__next__` method.
 
 Any :term:`iterable` object must implement the :c:member:`~PyTypeObject.tp_iter`

Doc/extending/newtypes_tutorial.rst

@@ -145,7 +145,7 @@ only used for variable-sized objects and should otherwise be zero.
    :c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have problems with multiple
    inheritance.  A Python subclass of your type will have to list your type first
    in its :attr:`~class.__bases__`, or else it will not be able to call your type's
-   :meth:`__new__` method without getting an error.  You can avoid this problem by
+   :meth:`~object.__new__` method without getting an error.  You can avoid this problem by
    ensuring that your type has a larger value for :c:member:`~PyTypeObject.tp_basicsize` than its
    base type does.  Most of the time, this will be true anyway, because either your
    base type will be :class:`object`, or else you will be adding data members to
@@ -164,14 +164,14 @@ We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. ::
    .tp_doc = PyDoc_STR("Custom objects"),
 
 To enable object creation, we have to provide a :c:member:`~PyTypeObject.tp_new`
-handler.  This is the equivalent of the Python method :meth:`__new__`, but
+handler.  This is the equivalent of the Python method :meth:`~object.__new__`, but
 has to be specified explicitly.  In this case, we can just use the default
 implementation provided by the API function :c:func:`PyType_GenericNew`. ::
 
    .tp_new = PyType_GenericNew,
 
 Everything else in the file should be familiar, except for some code in
-:c:func:`PyInit_custom`::
+:c:func:`!PyInit_custom`::
 
    if (PyType_Ready(&CustomType) < 0)
        return;
@@ -218,7 +218,7 @@ Of course, the current Custom type is pretty uninteresting. It has no data and
 doesn't do anything. It can't even be subclassed.
 
 .. note::
-   While this documentation showcases the standard :mod:`distutils` module
+   While this documentation showcases the standard :mod:`!distutils` module
    for building C extensions, it is recommended in real-world use cases to
    use the newer and better-maintained ``setuptools`` library.  Documentation
    on how to do this is out of scope for this document and can be found in
@@ -270,7 +270,7 @@ This method first clears the reference counts of the two Python attributes.
 ``NULL`` (which might happen here if ``tp_new`` failed midway).  It then
 calls the :c:member:`~PyTypeObject.tp_free` member of the object's type
 (computed by ``Py_TYPE(self)``) to free the object's memory.  Note that
-the object's type might not be :class:`CustomType`, because the object may
+the object's type might not be :class:`!CustomType`, because the object may
 be an instance of a subclass.
 
 .. note::
@@ -309,7 +309,7 @@ and install it in the :c:member:`~PyTypeObject.tp_new` member::
    .tp_new = Custom_new,
 
 The ``tp_new`` handler is responsible for creating (as opposed to initializing)
-objects of the type.  It is exposed in Python as the :meth:`__new__` method.
+objects of the type.  It is exposed in Python as the :meth:`~object.__new__` method.
 It is not required to define a ``tp_new`` member, and indeed many extension
 types will simply reuse :c:func:`PyType_GenericNew` as done in the first
 version of the :class:`!Custom` type above.  In this case, we use the ``tp_new``
@@ -343,7 +343,7 @@ result against ``NULL`` before proceeding.
 
 .. note::
    If you are creating a co-operative :c:member:`~PyTypeObject.tp_new` (one
-   that calls a base type's :c:member:`~PyTypeObject.tp_new` or :meth:`__new__`),
+   that calls a base type's :c:member:`~PyTypeObject.tp_new` or :meth:`~object.__new__`),
    you must *not* try to determine what method to call using method resolution
    order at runtime.  Always statically determine what type you are going to
    call, and call its :c:member:`~PyTypeObject.tp_new` directly, or via
@@ -386,14 +386,14 @@ by filling the :c:member:`~PyTypeObject.tp_init` slot. ::
    .tp_init = (initproc) Custom_init,
 
 The :c:member:`~PyTypeObject.tp_init` slot is exposed in Python as the
-:meth:`__init__` method.  It is used to initialize an object after it's
+:meth:`~object.__init__` method.  It is used to initialize an object after it's
 created.  Initializers always accept positional and keyword arguments,
 and they should return either ``0`` on success or ``-1`` on error.
 
 Unlike the ``tp_new`` handler, there is no guarantee that ``tp_init``
 is called at all (for example, the :mod:`pickle` module by default
-doesn't call :meth:`__init__` on unpickled instances).  It can also be
-called multiple times.  Anyone can call the :meth:`__init__` method on
+doesn't call :meth:`~object.__init__` on unpickled instances).  It can also be
+called multiple times.  Anyone can call the :meth:`!__init__` method on
 our objects.  For this reason, we have to be extra careful when assigning
 the new attribute values.  We might be tempted, for example to assign the
 ``first`` member like this::
@@ -706,8 +706,8 @@ participate in cycles::
    }
 
 For each subobject that can participate in cycles, we need to call the
-:c:func:`visit` function, which is passed to the traversal method. The
-:c:func:`visit` function takes as arguments the subobject and the extra argument
+:c:func:`!visit` function, which is passed to the traversal method. The
+:c:func:`!visit` function takes as arguments the subobject and the extra argument
 *arg* passed to the traversal method.  It returns an integer value that must be
 returned if it is non-zero.
 
@@ -789,9 +789,9 @@ types. It is easiest to inherit from the built in types, since an extension can
 easily use the :c:type:`PyTypeObject` it needs. It can be difficult to share
 these :c:type:`PyTypeObject` structures between extension modules.
 
-In this example we will create a :class:`SubList` type that inherits from the
+In this example we will create a :class:`!SubList` type that inherits from the
 built-in :class:`list` type. The new type will be completely compatible with
-regular lists, but will have an additional :meth:`increment` method that
+regular lists, but will have an additional :meth:`!increment` method that
 increases an internal counter:
 
 .. code-block:: pycon
@@ -821,7 +821,7 @@ The primary difference for derived type objects is that the base type's
 object structure must be the first value.  The base type will already include
 the :c:func:`PyObject_HEAD` at the beginning of its structure.
 
-When a Python object is a :class:`SubList` instance, its ``PyObject *`` pointer
+When a Python object is a :class:`!SubList` instance, its ``PyObject *`` pointer
 can be safely cast to both ``PyListObject *`` and ``SubListObject *``::
 
    static int
@@ -833,7 +833,7 @@ can be safely cast to both ``PyListObject *`` and ``SubListObject *``::
        return 0;
    }
 
-We see above how to call through to the :attr:`__init__` method of the base
+We see above how to call through to the :meth:`~object.__init__` method of the base
 type.
 
 This pattern is important when writing a type with custom