bpo-40204: Update documentation formatting for Sphinx 3.0

Doc/c-api/arg.rst

@@ -59,9 +59,9 @@ which disallows mutable objects such as :class:`bytearray`.
    the length argument (int or :c:type:`Py_ssize_t`) is controlled by
    defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including
    :file:`Python.h`.  If the macro was defined, length is a
-   :c:type:`Py_ssize_t` rather than an :c:type:`int`. This behavior will change
+   :c:type:`Py_ssize_t` rather than an :c:expr:`int`. This behavior will change
    in a future Python version to only support :c:type:`Py_ssize_t` and
-   drop :c:type:`int` support. It is best to always define :c:macro:`PY_SSIZE_T_CLEAN`.
+   drop :c:expr:`int` support. It is best to always define :c:macro:`PY_SSIZE_T_CLEAN`.
 
 
 ``s`` (:class:`str`) [const char \*]
@@ -131,12 +131,12 @@ which disallows mutable objects such as :class:`bytearray`.
 ``S`` (:class:`bytes`) [PyBytesObject \*]
    Requires that the Python object is a :class:`bytes` object, without
    attempting any conversion.  Raises :exc:`TypeError` if the object is not
-   a bytes object.  The C variable may also be declared as :c:type:`PyObject\*`.
+   a bytes object.  The C variable may also be declared as :c:expr:`PyObject*`.
 
 ``Y`` (:class:`bytearray`) [PyByteArrayObject \*]
    Requires that the Python object is a :class:`bytearray` object, without
    attempting any conversion.  Raises :exc:`TypeError` if the object is not
-   a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject\*`.
+   a :class:`bytearray` object. The C variable may also be declared as :c:expr:`PyObject*`.
 
 ``u`` (:class:`str`) [const Py_UNICODE \*]
    Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
@@ -183,7 +183,7 @@ which disallows mutable objects such as :class:`bytearray`.
 ``U`` (:class:`str`) [PyObject \*]
    Requires that the Python object is a Unicode object, without attempting
    any conversion.  Raises :exc:`TypeError` if the object is not a Unicode
-   object.  The C variable may also be declared as :c:type:`PyObject\*`.
+   object.  The C variable may also be declared as :c:expr:`PyObject*`.
 
 ``w*`` (read-write :term:`bytes-like object`) [Py_buffer]
    This format accepts any object which implements the read-write buffer
@@ -196,15 +196,15 @@ which disallows mutable objects such as :class:`bytearray`.
    It only works for encoded data without embedded NUL bytes.
 
    This format requires two arguments.  The first is only used as input, and
-   must be a :c:type:`const char\*` which points to the name of an encoding as a
+   must be a :c:expr:`const char*` which points to the name of an encoding as a
    NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
    An exception is raised if the named encoding is not known to Python.  The
-   second argument must be a :c:type:`char\*\*`; the value of the pointer it
+   second argument must be a :c:expr:`char**`; the value of the pointer it
    references will be set to a buffer with the contents of the argument text.
    The text will be encoded in the encoding specified by the first argument.
 
    :c:func:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy the
-   encoded data into this buffer and adjust *\*buffer* to reference the newly
+   encoded data into this buffer and adjust :c:expr:`*buffer` to reference the newly
    allocated storage.  The caller is responsible for calling :c:func:`PyMem_Free` to
    free the allocated buffer after use.
 
@@ -219,10 +219,10 @@ which disallows mutable objects such as :class:`bytearray`.
    characters.
 
    It requires three arguments.  The first is only used as input, and must be a
-   :c:type:`const char\*` which points to the name of an encoding as a
+   :c:expr:`const char*` which points to the name of an encoding as a
    NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
    An exception is raised if the named encoding is not known to Python.  The
-   second argument must be a :c:type:`char\*\*`; the value of the pointer it
+   second argument must be a :c:expr:`char**`; the value of the pointer it
    references will be set to a buffer with the contents of the argument text.
    The text will be encoded in the encoding specified by the first argument.
    The third argument must be a pointer to an integer; the referenced integer
@@ -254,59 +254,59 @@ Numbers
 
 ``b`` (:class:`int`) [unsigned char]
    Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
-   :c:type:`unsigned char`.
+   :c:expr:`unsigned char`.
 
 ``B`` (:class:`int`) [unsigned char]
    Convert a Python integer to a tiny int without overflow checking, stored in a C
-   :c:type:`unsigned char`.
+   :c:expr:`unsigned char`.
 
 ``h`` (:class:`int`) [short int]
-   Convert a Python integer to a C :c:type:`short int`.
+   Convert a Python integer to a C :c:expr:`short int`.
 
 ``H`` (:class:`int`) [unsigned short int]
-   Convert a Python integer to a C :c:type:`unsigned short int`, without overflow
+   Convert a Python integer to a C :c:expr:`unsigned short int`, without overflow
    checking.
 
 ``i`` (:class:`int`) [int]
-   Convert a Python integer to a plain C :c:type:`int`.
+   Convert a Python integer to a plain C :c:expr:`int`.
 
 ``I`` (:class:`int`) [unsigned int]
-   Convert a Python integer to a C :c:type:`unsigned int`, without overflow
+   Convert a Python integer to a C :c:expr:`unsigned int`, without overflow
    checking.
 
 ``l`` (:class:`int`) [long int]
-   Convert a Python integer to a C :c:type:`long int`.
+   Convert a Python integer to a C :c:expr:`long int`.
 
 ``k`` (:class:`int`) [unsigned long]
-   Convert a Python integer to a C :c:type:`unsigned long` without
+   Convert a Python integer to a C :c:expr:`unsigned long` without
    overflow checking.
 
 ``L`` (:class:`int`) [long long]
-   Convert a Python integer to a C :c:type:`long long`.
+   Convert a Python integer to a C :c:expr:`long long`.
 
 ``K`` (:class:`int`) [unsigned long long]
-   Convert a Python integer to a C :c:type:`unsigned long long`
+   Convert a Python integer to a C :c:expr:`unsigned long long`
    without overflow checking.
 
 ``n`` (:class:`int`) [Py_ssize_t]
-   Convert a Python integer to a C :c:type:`Py_ssize_t`.
+   Convert a Python integer to a C :c:expr:`Py_ssize_t`.
 
 ``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char]
    Convert a Python byte, represented as a :class:`bytes` or
-   :class:`bytearray` object of length 1, to a C :c:type:`char`.
+   :class:`bytearray` object of length 1, to a C :c:expr:`char`.
 
    .. versionchanged:: 3.3
       Allow :class:`bytearray` objects.
 
 ``C`` (:class:`str` of length 1) [int]
    Convert a Python character, represented as a :class:`str` object of
-   length 1, to a C :c:type:`int`.
+   length 1, to a C :c:expr:`int`.
 
 ``f`` (:class:`float`) [float]
-   Convert a Python floating point number to a C :c:type:`float`.
+   Convert a Python floating point number to a C :c:expr:`float`.
 
 ``d`` (:class:`float`) [double]
-   Convert a Python floating point number to a C :c:type:`double`.
+   Convert a Python floating point number to a C :c:expr:`double`.
 
 ``D`` (:class:`complex`) [Py_complex]
    Convert a Python complex number to a C :c:type:`Py_complex` structure.
@@ -322,7 +322,7 @@ Other objects
 ``O!`` (object) [*typeobject*, PyObject \*]
    Store a Python object in a C object pointer.  This is similar to ``O``, but
    takes two C arguments: the first is the address of a Python type object, the
-   second is the address of the C variable (of type :c:type:`PyObject\*`) into which
+   second is the address of the C variable (of type :c:expr:`PyObject*`) into which
    the object pointer is stored.  If the Python object does not have the required
    type, :exc:`TypeError` is raised.
 
@@ -331,13 +331,13 @@ Other objects
 ``O&`` (object) [*converter*, *anything*]
    Convert a Python object to a C variable through a *converter* function.  This
    takes two arguments: the first is a function, the second is the address of a C
-   variable (of arbitrary type), converted to :c:type:`void \*`.  The *converter*
+   variable (of arbitrary type), converted to :c:expr:`void*`.  The *converter*
    function in turn is called as follows::
 
       status = converter(object, address);
 
    where *object* is the Python object to be converted and *address* is the
-   :c:type:`void\*` argument that was passed to the :c:func:`PyArg_Parse\*` function.
+   :c:expr:`void*` argument that was passed to the ``PyArg_Parse*`` functions.
    The returned *status* should be ``1`` for a successful conversion and ``0`` if
    the conversion has failed.  When the conversion fails, the *converter* function
    should raise an exception and leave the content of *address* unmodified.
@@ -411,9 +411,9 @@ what is specified for the corresponding format unit in that case.
 
 For the conversion to succeed, the *arg* object must match the format
 and the format must be exhausted.  On success, the
-:c:func:`PyArg_Parse\*` functions return true, otherwise they return
+``PyArg_Parse*`` functions return true, otherwise they return
 false and raise an appropriate exception. When the
-:c:func:`PyArg_Parse\*` functions fail due to conversion failure in one
+``PyArg_Parse*`` functions fail due to conversion failure in one
 of the format units, the variables at the addresses corresponding to that
 and the following format units are left untouched.
 
@@ -483,7 +483,7 @@ API Functions
    *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
    arguments must be passed to the function, each of which should be a pointer to a
-   :c:type:`PyObject\*` variable; these will be filled in with the values from
+   :c:expr:`PyObject*` variable; these will be filled in with the values from
    *args*; they will contain borrowed references.  The variables which correspond
    to optional parameters not given by *args* will not be filled in; these should
    be initialized by the caller. This function returns true on success and false if
@@ -519,7 +519,7 @@ Building values
 .. c:function:: PyObject* Py_BuildValue(const char *format, ...)
 
    Create a new value based on a format string similar to those accepted by the
-   :c:func:`PyArg_Parse\*` family of functions and a sequence of values.  Returns
+   ``PyArg_Parse*`` family of functions and a sequence of values.  Returns
    the value or ``NULL`` in the case of an error; an exception will be raised if
    ``NULL`` is returned.
 
@@ -585,54 +585,54 @@ Building values
       Same as ``s#``.
 
    ``i`` (:class:`int`) [int]
-      Convert a plain C :c:type:`int` to a Python integer object.
+      Convert a plain C :c:expr:`int` to a Python integer object.
 
    ``b`` (:class:`int`) [char]
-      Convert a plain C :c:type:`char` to a Python integer object.
+      Convert a plain C :c:expr:`char` to a Python integer object.
 
    ``h`` (:class:`int`) [short int]
-      Convert a plain C :c:type:`short int` to a Python integer object.
+      Convert a plain C :c:expr:`short int` to a Python integer object.
 
    ``l`` (:class:`int`) [long int]
-      Convert a C :c:type:`long int` to a Python integer object.
+      Convert a C :c:expr:`long int` to a Python integer object.
 
    ``B`` (:class:`int`) [unsigned char]
-      Convert a C :c:type:`unsigned char` to a Python integer object.
+      Convert a C :c:expr:`unsigned char` to a Python integer object.
 
    ``H`` (:class:`int`) [unsigned short int]
-      Convert a C :c:type:`unsigned short int` to a Python integer object.
+      Convert a C :c:expr:`unsigned short int` to a Python integer object.
 
    ``I`` (:class:`int`) [unsigned int]
-      Convert a C :c:type:`unsigned int` to a Python integer object.
+      Convert a C :c:expr:`unsigned int` to a Python integer object.
 
    ``k`` (:class:`int`) [unsigned long]
-      Convert a C :c:type:`unsigned long` to a Python integer object.
+      Convert a C :c:expr:`unsigned long` to a Python integer object.
 
    ``L`` (:class:`int`) [long long]
-      Convert a C :c:type:`long long` to a Python integer object.
+      Convert a C :c:expr:`long long` to a Python integer object.
 
    ``K`` (:class:`int`) [unsigned long long]
-      Convert a C :c:type:`unsigned long long` to a Python integer object.
+      Convert a C :c:expr:`unsigned long long` to a Python integer object.
 
    ``n`` (:class:`int`) [Py_ssize_t]
-      Convert a C :c:type:`Py_ssize_t` to a Python integer.
+      Convert a C :c:expr:`Py_ssize_t` to a Python integer.
 
    ``c`` (:class:`bytes` of length 1) [char]
-      Convert a C :c:type:`int` representing a byte to a Python :class:`bytes` object of
+      Convert a C :c:expr:`int` representing a byte to a Python :class:`bytes` object of
       length 1.
 
    ``C`` (:class:`str` of length 1) [int]
-      Convert a C :c:type:`int` representing a character to Python :class:`str`
+      Convert a C :c:expr:`int` representing a character to Python :class:`str`
       object of length 1.
 
    ``d`` (:class:`float`) [double]
-      Convert a C :c:type:`double` to a Python floating point number.
+      Convert a C :c:expr:`double` to a Python floating point number.
 
    ``f`` (:class:`float`) [float]
-      Convert a C :c:type:`float` to a Python floating point number.
+      Convert a C :c:expr:`float` to a Python floating point number.
 
    ``D`` (:class:`complex`) [Py_complex \*]
-      Convert a C :c:type:`Py_complex` structure to a Python complex number.
+      Convert a C :c:expr:`Py_complex` structure to a Python complex number.
 
    ``O`` (object) [PyObject \*]
       Pass a Python object untouched (except for its reference count, which is
@@ -652,9 +652,9 @@ Building values
 
    ``O&`` (object) [*converter*, *anything*]
       Convert *anything* to a Python object through a *converter* function.  The
-      function is called with *anything* (which should be compatible with :c:type:`void
-      \*`) as its argument and should return a "new" Python object, or ``NULL`` if an
-      error occurred.
+	  function is called with *anything* (which should be compatible with
+	  :c:expr:`void*`)as its argument and should return a "new" Python object, or
+	  ``NULL`` if an error occurred.
 
    ``(items)`` (:class:`tuple`) [*matching-items*]
       Convert a sequence of C values to a Python tuple with the same number of items.

Doc/c-api/buffer.rst

@@ -438,12 +438,12 @@ Buffer-related functions
 
    Send a request to *exporter* to fill in *view* as specified by  *flags*.
    If the exporter cannot provide a buffer of the exact type, it MUST raise
-   :c:data:`PyExc_BufferError`, set :c:member:`view->obj` to ``NULL`` and
+   :c:data:`PyExc_BufferError`, set :c:expr:`view->obj` to ``NULL`` and
    return ``-1``.
 
-   On success, fill in *view*, set :c:member:`view->obj` to a new reference
+   On success, fill in *view*, set :c:expr:`view->obj` to a new reference
    to *exporter* and return 0. In the case of chained buffer providers
-   that redirect requests to a single object, :c:member:`view->obj` MAY
+   that redirect requests to a single object, :c:expr:`view->obj` MAY
    refer to this object instead of *exporter* (See :ref:`Buffer Object Structures <buffer-structs>`).
 
    Successful calls to :c:func:`PyObject_GetBuffer` must be paired with calls
@@ -455,7 +455,7 @@ Buffer-related functions
 .. c:function:: void PyBuffer_Release(Py_buffer *view)
 
    Release the buffer *view* and decrement the reference count for
-   :c:member:`view->obj`. This function MUST be called when the buffer
+   :c:expr:`view->obj`. This function MUST be called when the buffer
    is no longer being used, otherwise reference leaks may occur.
 
    It is an error to call this function on a buffer that was not obtained via
@@ -516,9 +516,9 @@ Buffer-related functions
    *view* as specified by flags, unless *buf* has been designated as read-only
    and :c:macro:`PyBUF_WRITABLE` is set in *flags*.
 
-   On success, set :c:member:`view->obj` to a new reference to *exporter* and
+   On success, set :c:expr:`view->obj` to a new reference to *exporter* and
    return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
-   :c:member:`view->obj` to ``NULL`` and return ``-1``;
+   :c:expr:`view->obj` to ``NULL`` and return ``-1``;
 
    If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
    *exporter* MUST be set to the exporting object and *flags* must be passed

Doc/c-api/call.rst

@@ -84,7 +84,7 @@ This is a pointer to a function with the following signature:
    and they must be unique.
    If there are no keyword arguments, then *kwnames* can instead be *NULL*.
 
-.. c:var:: PY_VECTORCALL_ARGUMENTS_OFFSET
+.. c:macro:: PY_VECTORCALL_ARGUMENTS_OFFSET
 
    If this flag is set in a vectorcall *nargsf* argument, the callee is allowed
    to temporarily change ``args[-1]``. In other words, *args* points to
@@ -283,7 +283,7 @@ please see individual documentation for details.
 
    This is the equivalent of the Python expression: ``callable(*args)``.
 
-   Note that if you only pass :c:type:`PyObject \*` args,
+   Note that if you only pass :c:expr:`PyObject*` args,
    :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
 
    .. versionchanged:: 3.4
@@ -304,7 +304,7 @@ please see individual documentation for details.
    This is the equivalent of the Python expression:
    ``obj.name(arg1, arg2, ...)``.
 
-   Note that if you only pass :c:type:`PyObject \*` args,
+   Note that if you only pass :c:expr:`PyObject*` args,
    :c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
 
    .. versionchanged:: 3.4
@@ -314,7 +314,7 @@ please see individual documentation for details.
 .. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
 
    Call a callable Python object *callable*, with a variable number of
-   :c:type:`PyObject \*` arguments.  The arguments are provided as a variable number
+   :c:expr:`PyObject*` arguments.  The arguments are provided as a variable number
    of parameters followed by *NULL*.
 
    Return the result of the call on success, or raise an exception and return
@@ -328,7 +328,7 @@ please see individual documentation for details.
 
    Call a method of the Python object *obj*, where the name of the method is given as a
    Python string object in *name*.  It is called with a variable number of
-   :c:type:`PyObject \*` arguments.  The arguments are provided as a variable number
+   :c:expr:`PyObject*` arguments.  The arguments are provided as a variable number
    of parameters followed by *NULL*.
 
    Return the result of the call on success, or raise an exception and return

Doc/c-api/capsule.rst

@@ -15,7 +15,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
 .. c:type:: PyCapsule
 
    This subtype of :c:type:`PyObject` represents an opaque value, useful for C
-   extension modules who need to pass an opaque value (as a :c:type:`void\*`
+   extension modules who need to pass an opaque value (as a :c:expr:`void*`
    pointer) through Python code to other C code.  It is often used to make a C
    function pointer defined in one module available to other modules, so the
    regular import mechanism can be used to access C APIs defined in dynamically

Doc/c-api/complex.rst

@@ -115,12 +115,12 @@ Complex Numbers as Python Objects
 
 .. c:function:: double PyComplex_RealAsDouble(PyObject *op)
 
-   Return the real part of *op* as a C :c:type:`double`.
+   Return the real part of *op* as a C :c:expr:`double`.
 
 
 .. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
 
-   Return the imaginary part of *op* as a C :c:type:`double`.
+   Return the imaginary part of *op* as a C :c:expr:`double`.
 
 
 .. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)