[3.11] gh-106919: Use role :c:macro: for referencing the C "constants" (GH-106920) (GH-106952)

(cherry picked from commit fcc816d)

Author: serhiy-storchaka

Doc/c-api/arg.rst

@@ -380,7 +380,7 @@ Other objects
    *items*.  Format units for sequences may be nested.
 
 It is possible to pass "long" integers (integers whose value exceeds the
-platform's :const:`LONG_MAX`) however no proper range checking is done --- the
+platform's :c:macro:`LONG_MAX`) however no proper range checking is done --- the
 most significant bits are silently truncated when the receiving field is too
 small to receive the value (actually, the semantics are inherited from downcasts
 in C --- your mileage may vary).
@@ -492,7 +492,7 @@ API Functions
 
    A simpler form of parameter retrieval which does not use a format string to
    specify the types of the arguments.  Functions which use this method to retrieve
-   their parameters should be declared as :const:`METH_VARARGS` in function or
+   their parameters should be declared as :c:macro:`METH_VARARGS` in function or
    method tables.  The tuple containing the actual parameters should be passed as
    *args*; it must actually be a tuple.  The length of the tuple must be at least
    *min* and no more than *max*; *min* and *max* may be equal.  Additional

Doc/c-api/call.rst

@@ -63,7 +63,7 @@ the arguments to an args tuple and kwargs dict anyway, then there is no point
 in implementing vectorcall.
 
 Classes can implement the vectorcall protocol by enabling the
-:const:`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
+:c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
 :c:member:`~PyTypeObject.tp_vectorcall_offset` to the offset inside the
 object structure where a *vectorcallfunc* appears.
 This is a pointer to a function with the following signature:
@@ -75,7 +75,7 @@ This is a pointer to a function with the following signature:
    values of the keyword arguments.
    This can be *NULL* if there are no arguments.
 - *nargsf* is the number of positional arguments plus possibly the
-   :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag.
+   :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag.
    To get the actual number of positional arguments from *nargsf*,
    use :c:func:`PyVectorcall_NARGS`.
 - *kwnames* is a tuple containing the names of the keyword arguments;
@@ -95,7 +95,7 @@ This is a pointer to a function with the following signature:
    ``args[0]`` may be changed.
 
    Whenever they can do so cheaply (without additional allocation), callers
-   are encouraged to use :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
+   are encouraged to use :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
    Doing so will allow callables such as bound methods to make their onward
    calls (which include a prepended *self* argument) very efficiently.
 
@@ -165,7 +165,7 @@ Vectorcall Support API
 
    This is a specialized function, intended to be put in the
    :c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``.
-   It does not check the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag
+   It does not check the :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag
    and it does not fall back to ``tp_call``.
 
    .. versionadded:: 3.8
@@ -383,11 +383,11 @@ please see individual documentation for details.
    *args[0]*, and the *args* array starting at *args[1]* represents the arguments
    of the call. There must be at least one positional argument.
    *nargsf* is the number of positional arguments including *args[0]*,
-   plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
+   plus :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
    temporarily be changed. Keyword arguments can be passed just like in
    :c:func:`PyObject_Vectorcall`.
 
-   If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
+   If the object has the :c:macro:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
    this will call the unbound method object with the full
    *args* vector as arguments.
 

Doc/c-api/complex.rst

@@ -64,7 +64,7 @@ pointers.  This is consistent throughout the API.
    representation.
 
    If *divisor* is null, this method returns zero and sets
-   :c:data:`errno` to :c:data:`EDOM`.
+   :c:data:`errno` to :c:macro:`EDOM`.
 
 
 .. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
@@ -73,7 +73,7 @@ pointers.  This is consistent throughout the API.
    representation.
 
    If *num* is null and *exp* is not a positive real number,
-   this method returns zero and sets :c:data:`errno` to :c:data:`EDOM`.
+   this method returns zero and sets :c:data:`errno` to :c:macro:`EDOM`.
 
 
 Complex Numbers as Python Objects

Doc/c-api/exceptions.rst

@@ -154,7 +154,7 @@ For convenience, some of these functions will always return a
    tuple object whose first item is the integer :c:data:`errno` value and whose
    second item is the corresponding error message (gotten from :c:func:`strerror`),
    and then calls ``PyErr_SetObject(type, object)``.  On Unix, when the
-   :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,
+   :c:data:`errno` value is :c:macro:`EINTR`, indicating an interrupted system call,
    this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
    leaves it set to that.  The function always returns ``NULL``, so a wrapper
    function around a system call can write ``return PyErr_SetFromErrno(type);``
@@ -567,7 +567,7 @@ Signal Handling
    be interruptible by user requests (such as by pressing Ctrl-C).
 
    .. note::
-      The default Python signal handler for :const:`SIGINT` raises the
+      The default Python signal handler for :c:macro:`SIGINT` raises the
       :exc:`KeyboardInterrupt` exception.
 
 
@@ -578,7 +578,7 @@ Signal Handling
       single: SIGINT
       single: KeyboardInterrupt (built-in exception)
 
-   Simulate the effect of a :const:`SIGINT` signal arriving.
+   Simulate the effect of a :c:macro:`SIGINT` signal arriving.
    This is equivalent to ``PyErr_SetInterruptEx(SIGINT)``.
 
    .. note::
@@ -690,7 +690,7 @@ Exception Objects
 
 .. c:function:: PyObject* PyException_GetCause(PyObject *ex)
 
-   Return the cause (either an exception instance, or :const:`None`,
+   Return the cause (either an exception instance, or ``None``,
    set by ``raise ... from ...``) associated with the exception as a new
    reference, as accessible from Python through :attr:`__cause__`.
 
@@ -699,7 +699,7 @@ Exception Objects
 
    Set the cause associated with the exception to *cause*.  Use ``NULL`` to clear
    it.  There is no type check to make sure that *cause* is either an exception
-   instance or :const:`None`.  This steals a reference to *cause*.
+   instance or ``None``.  This steals a reference to *cause*.
 
    :attr:`__suppress_context__` is implicitly set to ``True`` by this function.
 
@@ -788,7 +788,7 @@ because the :ref:`call protocol <call>` takes care of recursion handling.
 
    Marks a point where a recursive C-level call is about to be performed.
 
-   If :const:`USE_STACKCHECK` is defined, this function checks if the OS
+   If :c:macro:`USE_STACKCHECK` is defined, this function checks if the OS
    stack overflowed using :c:func:`PyOS_CheckStack`.  In this is the case, it
    sets a :exc:`MemoryError` and returns a nonzero value.
 

Doc/c-api/file.rst

@@ -93,7 +93,7 @@ the :mod:`io` APIs instead.
    .. index:: single: Py_PRINT_RAW
 
    Write object *obj* to file object *p*.  The only supported flag for *flags* is
-   :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
+   :c:macro:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
    instead of the :func:`repr`.  Return ``0`` on success or ``-1`` on failure; the
    appropriate exception will be set.
 

Doc/c-api/float.rst

@@ -109,7 +109,7 @@ Pack functions
 The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an
 :c:expr:`int` argument, non-zero if you want the bytes string in little-endian
 format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` ``p+7``), zero if you
-want big-endian format (exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN`
+want big-endian format (exponent first, at *p*). The :c:macro:`PY_BIG_ENDIAN`
 constant can be used to use the native endian: it is equal to ``1`` on big
 endian processor, or ``0`` on little endian processor.
 
@@ -140,7 +140,7 @@ Unpack functions
 The unpack routines read 2, 4 or 8 bytes, starting at *p*.  *le* is an
 :c:expr:`int` argument, non-zero if the bytes string is in little-endian format
 (exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-endian
-(exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN` constant can be used to
+(exponent first, at *p*). The :c:macro:`PY_BIG_ENDIAN` constant can be used to
 use the native endian: it is equal to ``1`` on big endian processor, or ``0``
 on little endian processor.
 

Doc/c-api/gcsupport.rst

@@ -13,14 +13,12 @@ or strings), do not need to provide any explicit support for garbage
 collection.
 
 To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of the type object must
-include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
+include the :c:macro:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
 :c:member:`~PyTypeObject.tp_traverse` handler.  If instances of the type are mutable, a
 :c:member:`~PyTypeObject.tp_clear` implementation must also be provided.
 
 
-.. data:: Py_TPFLAGS_HAVE_GC
-   :noindex:
-
+:c:macro:`Py_TPFLAGS_HAVE_GC`
    Objects with a type with this flag set must conform with the rules
    documented here.  For convenience these objects will be referred to as
    container objects.
@@ -52,18 +50,18 @@ rules:
       :c:member:`~PyTypeObject.tp_flags`, :c:member:`~PyTypeObject.tp_traverse`
       and :c:member:`~PyTypeObject.tp_clear` fields if the type inherits from a
       class that implements the garbage collector protocol and the child class
-      does *not* include the :const:`Py_TPFLAGS_HAVE_GC` flag.
+      does *not* include the :c:macro:`Py_TPFLAGS_HAVE_GC` flag.
 
 .. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
 
    Analogous to :c:func:`PyObject_New` but for container objects with the
-   :const:`Py_TPFLAGS_HAVE_GC` flag set.
+   :c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
 
 
 .. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
 
    Analogous to :c:func:`PyObject_NewVar` but for container objects with the
-   :const:`Py_TPFLAGS_HAVE_GC` flag set.
+   :c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
 
 
 .. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)

Doc/c-api/init.rst

@@ -1287,7 +1287,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
    function does not steal any references to *exc*. To prevent naive misuse, you
    must write your own C extension to call this.  Must be called with the GIL held.
    Returns the number of thread states modified; this is normally one, but will be
-   zero if the thread id isn't found.  If *exc* is :const:`NULL`, the pending
+   zero if the thread id isn't found.  If *exc* is ``NULL``, the pending
    exception (if any) for the thread is cleared. This raises no exceptions.
 
    .. versionchanged:: 3.7
@@ -1566,32 +1566,32 @@ Python-level trace functions in previous versions.
    The type of the trace function registered using :c:func:`PyEval_SetProfile` and
    :c:func:`PyEval_SetTrace`. The first parameter is the object passed to the
    registration function as *obj*, *frame* is the frame object to which the event
-   pertains, *what* is one of the constants :const:`PyTrace_CALL`,
-   :const:`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`,
-   :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, :const:`PyTrace_C_RETURN`,
-   or :const:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
-
-   +------------------------------+----------------------------------------+
-   | Value of *what*              | Meaning of *arg*                       |
-   +==============================+========================================+
-   | :const:`PyTrace_CALL`        | Always :c:data:`Py_None`.              |
-   +------------------------------+----------------------------------------+
-   | :const:`PyTrace_EXCEPTION`   | Exception information as returned by   |
-   |                              | :func:`sys.exc_info`.                  |
-   +------------------------------+----------------------------------------+
-   | :const:`PyTrace_LINE`        | Always :c:data:`Py_None`.              |
-   +------------------------------+----------------------------------------+
-   | :const:`PyTrace_RETURN`      | Value being returned to the caller,    |
-   |                              | or ``NULL`` if caused by an exception. |
-   +------------------------------+----------------------------------------+
-   | :const:`PyTrace_C_CALL`      | Function object being called.          |
-   +------------------------------+----------------------------------------+
-   | :const:`PyTrace_C_EXCEPTION` | Function object being called.          |
-   +------------------------------+----------------------------------------+
-   | :const:`PyTrace_C_RETURN`    | Function object being called.          |
-   +------------------------------+----------------------------------------+
-   | :const:`PyTrace_OPCODE`      | Always :c:data:`Py_None`.              |
-   +------------------------------+----------------------------------------+
+   pertains, *what* is one of the constants :c:data:`PyTrace_CALL`,
+   :c:data:`PyTrace_EXCEPTION`, :c:data:`PyTrace_LINE`, :c:data:`PyTrace_RETURN`,
+   :c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION`, :c:data:`PyTrace_C_RETURN`,
+   or :c:data:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
+
+   +-------------------------------+----------------------------------------+
+   | Value of *what*               | Meaning of *arg*                       |
+   +===============================+========================================+
+   | :c:data:`PyTrace_CALL`        | Always :c:data:`Py_None`.              |
+   +-------------------------------+----------------------------------------+
+   | :c:data:`PyTrace_EXCEPTION`   | Exception information as returned by   |
+   |                               | :func:`sys.exc_info`.                  |
+   +-------------------------------+----------------------------------------+
+   | :c:data:`PyTrace_LINE`        | Always :c:data:`Py_None`.              |
+   +-------------------------------+----------------------------------------+
+   | :c:data:`PyTrace_RETURN`      | Value being returned to the caller,    |
+   |                               | or ``NULL`` if caused by an exception. |
+   +-------------------------------+----------------------------------------+
+   | :c:data:`PyTrace_C_CALL`      | Function object being called.          |
+   +-------------------------------+----------------------------------------+
+   | :c:data:`PyTrace_C_EXCEPTION` | Function object being called.          |
+   +-------------------------------+----------------------------------------+
+   | :c:data:`PyTrace_C_RETURN`    | Function object being called.          |
+   +-------------------------------+----------------------------------------+
+   | :c:data:`PyTrace_OPCODE`      | Always :c:data:`Py_None`.              |
+   +-------------------------------+----------------------------------------+
 
 .. c:var:: int PyTrace_CALL
 
@@ -1658,8 +1658,8 @@ Python-level trace functions in previous versions.
    function as its first parameter, and may be any Python object, or ``NULL``.  If
    the profile function needs to maintain state, using a different value for *obj*
    for each thread provides a convenient and thread-safe place to store it.  The
-   profile function is called for all monitored events except :const:`PyTrace_LINE`
-   :const:`PyTrace_OPCODE` and :const:`PyTrace_EXCEPTION`.
+   profile function is called for all monitored events except :c:data:`PyTrace_LINE`
+   :c:data:`PyTrace_OPCODE` and :c:data:`PyTrace_EXCEPTION`.
 
    See also the :func:`sys.setprofile` function.
 
@@ -1672,8 +1672,8 @@ Python-level trace functions in previous versions.
    :c:func:`PyEval_SetProfile`, except the tracing function does receive line-number
    events and per-opcode events, but does not receive any event related to C function
    objects being called.  Any trace function registered using :c:func:`PyEval_SetTrace`
-   will not receive :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION` or
-   :const:`PyTrace_C_RETURN` as a value for the *what* parameter.
+   will not receive :c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION` or
+   :c:data:`PyTrace_C_RETURN` as a value for the *what* parameter.
 
    See also the :func:`sys.settrace` function.
 

Doc/c-api/long.rst

@@ -141,8 +141,8 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__`
    method (if present) to convert it to a :c:type:`PyLongObject`.
 
-   If the value of *obj* is greater than :const:`LONG_MAX` or less than
-   :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and
+   If the value of *obj* is greater than :c:macro:`LONG_MAX` or less than
+   :c:macro:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and
    return ``-1``; otherwise, set *\*overflow* to ``0``.  If any other exception
    occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
 
@@ -182,8 +182,8 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__` method
    (if present) to convert it to a :c:type:`PyLongObject`.
 
-   If the value of *obj* is greater than :const:`LLONG_MAX` or less than
-   :const:`LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
+   If the value of *obj* is greater than :c:macro:`LLONG_MAX` or less than
+   :c:macro:`LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
    and return ``-1``; otherwise, set *\*overflow* to ``0``.  If any other
    exception occurs set *\*overflow* to ``0`` and return ``-1`` as usual.