[3.12] gh-107091: Fix some uses of :attr: role (GH-107318) (GH-107330)

Fix also formatting of PyMethodDef members.
(cherry picked from commit d363eb5)

Doc/c-api/import.rst

@@ -294,23 +294,25 @@ Importing Modules
 
 .. c:struct:: _inittab
 
-   Structure describing a single entry in the list of built-in modules.  Each of
-   these structures gives the name and initialization function for a module built
-   into the interpreter.  The name is an ASCII encoded string.  Programs which
+   Structure describing a single entry in the list of built-in modules.
+   Programs which
    embed Python may use an array of these structures in conjunction with
    :c:func:`PyImport_ExtendInittab` to provide additional built-in modules.
-   The structure is defined in :file:`Include/import.h` as::
+   The structure consists of two members:
 
-      struct _inittab {
-          const char *name;           /* ASCII encoded string */
-          PyObject* (*initfunc)(void);
-      };
+   .. c:member:: const char *name
+
+      The module name, as an ASCII encoded string.
+
+   .. c: member:: PyObject* (*initfunc)(void)
+
+      Initialization function for a module built into the interpreter.
 
 
 .. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab)
 
    Add a collection of modules to the table of built-in modules.  The *newtab*
-   array must end with a sentinel entry which contains ``NULL`` for the :attr:`name`
+   array must end with a sentinel entry which contains ``NULL`` for the :c:member:`~_inittab.name`
    field; failure to provide the sentinel value can result in a memory fault.
    Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
    extend the internal table.  In the event of failure, no modules are added to the

Doc/c-api/init.rst

@@ -1023,8 +1023,11 @@ code, or when embedding the Python interpreter:
 .. c:type:: PyThreadState
 
    This data structure represents the state of a single thread.  The only public
-   data member is :attr:`interp` (:c:expr:`PyInterpreterState *`), which points to
-   this thread's interpreter state.
+   data member is:
+
+   .. c:member:: PyInterpreterState *interp
+
+      This thread's interpreter state.
 
 
 .. c:function:: void PyEval_InitThreads()

Doc/c-api/structures.rst

@@ -35,7 +35,7 @@ under :ref:`reference counting <countingrefs>`.
 
 .. c:type:: PyVarObject
 
-   This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size`
+   This is an extension of :c:type:`PyObject` that adds the :c:member:`~PyVarObject.ob_size`
    field.  This is only used for objects that have some notion of *length*.
    This type does not often appear in the Python/C API.
    Access to the members must be done by using the macros
@@ -152,7 +152,7 @@ under :ref:`reference counting <countingrefs>`.
 .. c:macro:: PyVarObject_HEAD_INIT(type, size)
 
    This is a macro which expands to initialization values for a new
-   :c:type:`PyVarObject` type, including the :attr:`ob_size` field.
+   :c:type:`PyVarObject` type, including the :c:member:`~PyVarObject.ob_size` field.
    This macro expands to::
 
       _PyObject_EXTRA_INIT
@@ -228,21 +228,21 @@ Implementing functions and methods
    Structure used to describe a method of an extension type.  This structure has
    four fields:
 
-   .. c:member:: const char* ml_name
+   .. c:member:: const char *ml_name
 
-      name of the method
+      Name of the method.
 
    .. c:member:: PyCFunction ml_meth
 
-      pointer to the C implementation
+      Pointer to the C implementation.
 
    .. c:member:: int ml_flags
 
-      flags bits indicating how the call should be constructed
+      Flags bits indicating how the call should be constructed.
 
-   .. c:member:: const char* ml_doc
+   .. c:member:: const char *ml_doc
 
-      points to the contents of the docstring
+      Points to the contents of the docstring.
 
 The :c:member:`~PyMethodDef.ml_meth` is a C function pointer.
 The functions may be of different

Doc/c-api/tuple.rst

@@ -164,7 +164,8 @@ type.
 
    Describes a field of a struct sequence. As a struct sequence is modeled as a
    tuple, all fields are typed as :c:expr:`PyObject*`.  The index in the
-   :attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
+   :c:member:`~PyStructSequence_Desc.fields` array of
+   the :c:type:`PyStructSequence_Desc` determines which
    field of the struct sequence is described.
 
    +-----------+------------------+-----------------------------------------+

Doc/c-api/typeobj.rst

@@ -485,17 +485,17 @@ PyObject Slots
 --------------
 
 The type object structure extends the :c:type:`PyVarObject` structure. The
-:attr:`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 :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 :attr:`ob_size` field.
+type objects) *must* have the :c:member:`~PyVarObject.ob_size` field.
 
 
 .. c:member:: Py_ssize_t PyObject.ob_refcnt
 
    This is the type object's reference count, initialized to ``1`` by the
    ``PyObject_HEAD_INIT`` macro.  Note that for :ref:`statically allocated type
-   objects <static-types>`, the type's instances (objects whose :attr:`ob_type`
+   objects <static-types>`, the type's instances (objects whose :c:member:`~PyObject.ob_type`
    points back to the type) do *not* count as references.  But for
    :ref:`dynamically allocated type objects <heap-types>`, the instances *do*
    count as references.
@@ -519,8 +519,8 @@ type objects) *must* have the :attr:`ob_size` field.
       Foo_Type.ob_type = &PyType_Type;
 
    This should be done before any instances of the type are created.
-   :c:func:`PyType_Ready` checks if :attr:`ob_type` is ``NULL``, and if so,
-   initializes it to the :attr:`ob_type` field of the base class.
+   :c:func:`PyType_Ready` checks if :c:member:`~PyObject.ob_type` is ``NULL``, and if so,
+   initializes it to the :c:member:`~PyObject.ob_type` field of the base class.
    :c:func:`PyType_Ready` will not change this field if it is non-zero.
 
    **Inheritance:**
@@ -619,20 +619,20 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    instances have the same size, given in :c:member:`~PyTypeObject.tp_basicsize`.
 
    For a type with variable-length instances, the instances must have an
-   :attr:`ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N
+   :c:member:`~PyVarObject.ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N
    times :c:member:`~PyTypeObject.tp_itemsize`, where N is the "length" of the object.  The value of
-   N is typically stored in the instance's :attr:`ob_size` field.  There are
-   exceptions:  for example, ints use a negative :attr:`ob_size` to indicate a
+   N is typically stored in the instance's :c:member:`~PyVarObject.ob_size` field.  There are
+   exceptions:  for example, ints use a negative :c:member:`~PyVarObject.ob_size` to indicate a
    negative number, and N is ``abs(ob_size)`` there.  Also, the presence of an
-   :attr:`ob_size` field in the instance layout doesn't mean that the instance
+   :c:member:`~PyVarObject.ob_size` field in the instance layout doesn't mean that the instance
    structure is variable-length (for example, the structure for the list type has
-   fixed-length instances, yet those instances have a meaningful :attr:`ob_size`
+   fixed-length instances, yet those instances have a meaningful :c:member:`~PyVarObject.ob_size`
    field).
 
    The basic size includes the fields in the instance declared by the macro
    :c:macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD` (whichever is used to
-   declare the instance struct) and this in turn includes the :attr:`_ob_prev` and
-   :attr:`_ob_next` fields if they are present.  This means that the only correct
+   declare the instance struct) and this in turn includes the  :c:member:`~PyObject._ob_prev` and
+   :c:member:`~PyObject._ob_next` fields if they are present.  This means that the only correct
    way to get an initializer for the :c:member:`~PyTypeObject.tp_basicsize` is to use the
    ``sizeof`` operator on the struct used to declare the instance layout.
    The basic size does not include the GC header size.
@@ -764,7 +764,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
    **Inheritance:**
 
-   Group: :attr:`tp_getattr`, :attr:`tp_getattro`
+   Group: :c:member:`~PyTypeObject.tp_getattr`, :c:member:`~PyTypeObject.tp_getattro`
 
    This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattro`: a subtype
    inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when
@@ -781,7 +781,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
    **Inheritance:**
 
-   Group: :attr:`tp_setattr`, :attr:`tp_setattro`
+   Group: :c:member:`~PyTypeObject.tp_setattr`, :c:member:`~PyTypeObject.tp_setattro`
 
    This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattro`: a subtype
    inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when
@@ -883,7 +883,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    normal return value; when an error occurs during the computation of the hash
    value, the function should set an exception and return ``-1``.
 
-   When this field is not set (*and* :attr:`tp_richcompare` is not set),
+   When this field is not set (*and* :c:member:`~PyTypeObject.tp_richcompare` is not set),
    an attempt to take the hash of the object raises :exc:`TypeError`.
    This is the same as setting it to :c:func:`PyObject_HashNotImplemented`.
 
@@ -897,7 +897,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
    **Inheritance:**
 
-   Group: :attr:`tp_hash`, :attr:`tp_richcompare`
+   Group: :c:member:`~PyTypeObject.tp_hash`, :c:member:`~PyTypeObject.tp_richcompare`
 
    This field is inherited by subtypes together with
    :c:member:`~PyTypeObject.tp_richcompare`: a subtype inherits both of
@@ -956,7 +956,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
    **Inheritance:**
 
-   Group: :attr:`tp_getattr`, :attr:`tp_getattro`
+   Group: :c:member:`~PyTypeObject.tp_getattr`, :c:member:`~PyTypeObject.tp_getattro`
 
    This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattr`: a subtype
    inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when
@@ -982,7 +982,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
    **Inheritance:**
 
-   Group: :attr:`tp_setattr`, :attr:`tp_setattro`
+   Group: :c:member:`~PyTypeObject.tp_setattr`, :c:member:`~PyTypeObject.tp_setattro`
 
    This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattr`: a subtype
    inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when
@@ -1047,7 +1047,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
       This bit is set when the type object itself is allocated on the heap, for
       example, types created dynamically using :c:func:`PyType_FromSpec`.  In this
-      case, the :attr:`ob_type` field of its instances is considered a reference to
+      case, the :c:member:`~PyObject.ob_type` field of its instances is considered a reference to
       the type, and the type object is INCREF'ed when a new instance is created, and
       DECREF'ed when an instance is destroyed (this does not apply to instances of
       subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or
@@ -1100,13 +1100,13 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
       **Inheritance:**
 
-      Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
+      Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :c:member:`~PyTypeObject.tp_traverse`, :c:member:`~PyTypeObject.tp_clear`
 
       The :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is inherited
-      together with the :attr:`tp_traverse` and :attr:`tp_clear`
+      together with the :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear`
       fields, i.e.  if the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is
-      clear in the subtype and the :attr:`tp_traverse` and
-      :attr:`tp_clear` fields in the subtype exist and have ``NULL``
+      clear in the subtype and the :c:member:`~PyTypeObject.tp_traverse` and
+      :c:member:`~PyTypeObject.tp_clear` fields in the subtype exist and have ``NULL``
       values.
 
 
@@ -1421,7 +1421,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
    **Inheritance:**
 
-   Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
+   Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :c:member:`~PyTypeObject.tp_traverse`, :c:member:`~PyTypeObject.tp_clear`
 
    This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_clear` and the
    :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
@@ -1488,7 +1488,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
    **Inheritance:**
 
-   Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
+   Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :c:member:`~PyTypeObject.tp_traverse`, :c:member:`~PyTypeObject.tp_clear`
 
    This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_traverse` and the
    :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
@@ -1547,7 +1547,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
    **Inheritance:**
 
-   Group: :attr:`tp_hash`, :attr:`tp_richcompare`
+   Group: :c:member:`~PyTypeObject.tp_hash`, :c:member:`~PyTypeObject.tp_richcompare`
 
    This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_hash`:
    a subtype inherits :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` when
@@ -1556,9 +1556,9 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
    **Default:**
 
-   :c:data:`PyBaseObject_Type` provides a :attr:`tp_richcompare`
+   :c:data:`PyBaseObject_Type` provides a :c:member:`~PyTypeObject.tp_richcompare`
    implementation, which may be inherited.  However, if only
-   :attr:`tp_hash` is defined, not even the inherited function is used
+   :c:member:`~PyTypeObject.tp_hash` is defined, not even the inherited function is used
    and instances of the type will not be able to participate in any
    comparisons.
 
@@ -2374,9 +2374,9 @@ Sequence Object Structures
    This slot must be filled for the :c:func:`PySequence_Check`
    function to return ``1``, it can be ``NULL`` otherwise.
 
-   Negative indexes are handled as follows: if the :attr:`sq_length` slot is
+   Negative indexes are handled as follows: if the :c:member:`~PySequenceMethods.sq_length` slot is
    filled, it is called and the sequence length is used to compute a positive
-   index which is passed to :attr:`sq_item`.  If :attr:`sq_length` is ``NULL``,
+   index which is passed to  :c:member:`~PySequenceMethods.sq_item`.  If :c:member:`!sq_length` is ``NULL``,
    the index is passed as is to the function.
 
 .. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item
@@ -2586,8 +2586,8 @@ Slot Type typedefs
    The purpose of this function is to separate memory allocation from memory
    initialization.  It should return a pointer to a block of memory of adequate
    length for the instance, suitably aligned, and initialized to zeros, but with
-   :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument.  If
-   the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, the object's :attr:`ob_size` field
+   :c:member:`~PyObject.ob_refcnt` set to ``1`` and :c:member:`~PyObject.ob_type` set to the type argument.  If
+   the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, the object's :c:member:`~PyVarObject.ob_size` field
    should be initialized to *nitems* and the length of the allocated memory block
    should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of
    ``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block

Doc/c-api/veryhigh.rst

@@ -353,7 +353,7 @@ the same library that the Python runtime is using.
    executed, it is passed as ``PyCompilerFlags *flags``.  In this case, ``from
    __future__ import`` can modify *flags*.
 
-   Whenever ``PyCompilerFlags *flags`` is ``NULL``, :attr:`cf_flags` is treated as
+   Whenever ``PyCompilerFlags *flags`` is ``NULL``, :c:member:`~PyCompilerFlags.cf_flags` is treated as
    equal to ``0``, and any modification due to ``from __future__ import`` is
    discarded.
 
@@ -367,7 +367,7 @@ the same library that the Python runtime is using.
       initialized to ``PY_MINOR_VERSION``.
 
       The field is ignored by default, it is used if and only if
-      ``PyCF_ONLY_AST`` flag is set in *cf_flags*.
+      ``PyCF_ONLY_AST`` flag is set in :c:member:`~PyCompilerFlags.cf_flags`.
 
    .. versionchanged:: 3.8
       Added *cf_feature_version* field.

Doc/extending/newtypes.rst

@@ -270,7 +270,7 @@ structure::
 One entry should be defined for each method provided by the type; no entries are
 needed for methods inherited from a base type.  One additional entry is needed
 at the end; it is a sentinel that marks the end of the array.  The
-:attr:`ml_name` field of the sentinel must be ``NULL``.
+:c:member:`~PyMethodDef.ml_name` field of the sentinel must be ``NULL``.
 
 The second table is used to define attributes which map directly to data stored
 in the instance.  A variety of primitive C types are supported, and access may

Doc/extending/newtypes_tutorial.rst

@@ -176,8 +176,8 @@ Everything else in the file should be familiar, except for some code in
    if (PyType_Ready(&CustomType) < 0)
        return;
 
-This initializes the :class:`Custom` type, filling in a number of members
-to the appropriate default values, including :attr:`ob_type` that we initially
+This initializes the :class:`!Custom` type, filling in a number of members
+to the appropriate default values, including :c:member:`~PyObject.ob_type` that we initially
 set to ``NULL``. ::
 
    Py_INCREF(&CustomType);

Doc/whatsnew/2.5.rst

@@ -954,7 +954,7 @@ The return value must be either a Python integer or long integer. The
 interpreter will check that the type returned is correct, and raises a
 :exc:`TypeError` if this requirement isn't met.
 
-A corresponding :attr:`nb_index` slot was added to the C-level
+A corresponding :c:member:`~PyNumberMethods.nb_index` slot was added to the C-level
 :c:type:`PyNumberMethods` structure to let C extensions implement this protocol.
 ``PyNumber_Index(obj)`` can be used in extension code to call the
 :meth:`__index__` function and retrieve its result.