Skip to content

Commit 7d0fef5

Browse files
authored
bpo-40204: Allow pre-Sphinx 3 syntax in the doc (pythonGH-21844) (pythonGH-21901) (pythonGH-21928)
* bpo-40204: Allow pre-Sphinx 3 syntax in the doc (pythonGH-21844) Enable Sphinx 3.2 "c_allow_pre_v3" option and disable the c_warn_on_allowed_pre_v3 option to make the documentation compatible with Sphinx 2 and Sphinx 3. (cherry picked from commit 423e77d) * bpo-40204: Fix Sphinx sytanx in howto/instrumentation.rst (pythonGH-21858) Use generic '.. object::' to declare markers, rather than abusing '.. c:function::' which fails on Sphinx 3. (cherry picked from commit 43577c0) * bpo-40204: Fix duplicates in the documentation (pythonGH-21857) Fix two Sphinx 3 issues: Doc/c-api/buffer.rst:304: WARNING: Duplicate C declaration, also defined in 'c-api/buffer'. Declaration is 'PyBUF_ND'. Doc/c-api/unicode.rst:1603: WARNING: Duplicate C declaration, also defined in 'c-api/unicode'. Declaration is 'PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)'. (cherry picked from commit 46d10b1) * bpo-40204: Add :noindex: in the documentation (pythonGH-21859) Add :noindex: to duplicated documentation to fix "duplicate object description" errors. For example, fix this Sphinx 3 issue: Doc/library/configparser.rst:1146: WARNING: duplicate object description of configparser.ConfigParser.optionxform, other instance in library/configparser, use :noindex: for one of them (cherry picked from commit d3ded08) * bpo-40204, doc: Fix syntax of C variables (pythonGH-21846) For example, fix the following Sphinx 3 errors: Doc/c-api/buffer.rst:102: WARNING: Error in declarator or parameters Invalid C declaration: Expected identifier in nested name. [error at 5] void \*obj -----^ Doc/c-api/arg.rst:130: WARNING: Unparseable C cross-reference: 'PyObject*' Invalid C declaration: Expected end of definition. [error at 8] PyObject* --------^ The modified documentation is compatible with Sphinx 2 and Sphinx 3. (cherry picked from commit 474652f) * bpo-40204: Fix reference to terms in the doc (pythonGH-21865) Sphinx 3 requires to refer to terms with the exact case. For example, fix the Sphinx 3 warning: Doc/library/pkgutil.rst:71: WARNING: term Loader not found in case sensitive match.made a reference to loader instead. (cherry picked from commit bb0b085) * bpo-40204: Fix duplicated productionlist names in the doc (pythonGH-21900) Sphinx 3 disallows having more than one productionlist markup with the same name. Simply remove names in this case, since names are not shown anyway. For example, fix the Sphinx 3 warning: Doc/reference/introduction.rst:96: duplicate token description of *:name, other instance in reference/expressions (cherry picked from commit 1abeda8) (cherry picked from commit 8f88190)
1 parent 34889a5 commit 7d0fef5

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+260
-246
lines changed

Doc/c-api/arg.rst

+13-13
Original file line numberDiff line numberDiff line change
@@ -131,12 +131,12 @@ which disallows mutable objects such as :class:`bytearray`.
131131
``S`` (:class:`bytes`) [PyBytesObject \*]
132132
Requires that the Python object is a :class:`bytes` object, without
133133
attempting any conversion. Raises :exc:`TypeError` if the object is not
134-
a bytes object. The C variable may also be declared as :c:type:`PyObject\*`.
134+
a bytes object. The C variable may also be declared as :c:type:`PyObject*`.
135135

136136
``Y`` (:class:`bytearray`) [PyByteArrayObject \*]
137137
Requires that the Python object is a :class:`bytearray` object, without
138138
attempting any conversion. Raises :exc:`TypeError` if the object is not
139-
a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject\*`.
139+
a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject*`.
140140

141141
``u`` (:class:`str`) [const Py_UNICODE \*]
142142
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`.
183183
``U`` (:class:`str`) [PyObject \*]
184184
Requires that the Python object is a Unicode object, without attempting
185185
any conversion. Raises :exc:`TypeError` if the object is not a Unicode
186-
object. The C variable may also be declared as :c:type:`PyObject\*`.
186+
object. The C variable may also be declared as :c:type:`PyObject*`.
187187

188188
``w*`` (read-write :term:`bytes-like object`) [Py_buffer]
189189
This format accepts any object which implements the read-write buffer
@@ -196,10 +196,10 @@ which disallows mutable objects such as :class:`bytearray`.
196196
It only works for encoded data without embedded NUL bytes.
197197

198198
This format requires two arguments. The first is only used as input, and
199-
must be a :c:type:`const char\*` which points to the name of an encoding as a
199+
must be a :c:type:`const char*` which points to the name of an encoding as a
200200
NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
201201
An exception is raised if the named encoding is not known to Python. The
202-
second argument must be a :c:type:`char\*\*`; the value of the pointer it
202+
second argument must be a :c:type:`char**`; the value of the pointer it
203203
references will be set to a buffer with the contents of the argument text.
204204
The text will be encoded in the encoding specified by the first argument.
205205

@@ -219,10 +219,10 @@ which disallows mutable objects such as :class:`bytearray`.
219219
characters.
220220

221221
It requires three arguments. The first is only used as input, and must be a
222-
:c:type:`const char\*` which points to the name of an encoding as a
222+
:c:type:`const char*` which points to the name of an encoding as a
223223
NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
224224
An exception is raised if the named encoding is not known to Python. The
225-
second argument must be a :c:type:`char\*\*`; the value of the pointer it
225+
second argument must be a :c:type:`char**`; the value of the pointer it
226226
references will be set to a buffer with the contents of the argument text.
227227
The text will be encoded in the encoding specified by the first argument.
228228
The third argument must be a pointer to an integer; the referenced integer
@@ -322,7 +322,7 @@ Other objects
322322
``O!`` (object) [*typeobject*, PyObject \*]
323323
Store a Python object in a C object pointer. This is similar to ``O``, but
324324
takes two C arguments: the first is the address of a Python type object, the
325-
second is the address of the C variable (of type :c:type:`PyObject\*`) into which
325+
second is the address of the C variable (of type :c:type:`PyObject*`) into which
326326
the object pointer is stored. If the Python object does not have the required
327327
type, :exc:`TypeError` is raised.
328328

@@ -331,13 +331,13 @@ Other objects
331331
``O&`` (object) [*converter*, *anything*]
332332
Convert a Python object to a C variable through a *converter* function. This
333333
takes two arguments: the first is a function, the second is the address of a C
334-
variable (of arbitrary type), converted to :c:type:`void \*`. The *converter*
334+
variable (of arbitrary type), converted to :c:type:`void *`. The *converter*
335335
function in turn is called as follows::
336336

337337
status = converter(object, address);
338338

339339
where *object* is the Python object to be converted and *address* is the
340-
:c:type:`void\*` argument that was passed to the :c:func:`PyArg_Parse\*` function.
340+
:c:type:`void*` argument that was passed to the :c:func:`PyArg_Parse\*` function.
341341
The returned *status* should be ``1`` for a successful conversion and ``0`` if
342342
the conversion has failed. When the conversion fails, the *converter* function
343343
should raise an exception and leave the content of *address* unmodified.
@@ -483,7 +483,7 @@ API Functions
483483
*args*; it must actually be a tuple. The length of the tuple must be at least
484484
*min* and no more than *max*; *min* and *max* may be equal. Additional
485485
arguments must be passed to the function, each of which should be a pointer to a
486-
:c:type:`PyObject\*` variable; these will be filled in with the values from
486+
:c:type:`PyObject*` variable; these will be filled in with the values from
487487
*args*; they will contain borrowed references. The variables which correspond
488488
to optional parameters not given by *args* will not be filled in; these should
489489
be initialized by the caller. This function returns true on success and false if
@@ -652,8 +652,8 @@ Building values
652652
653653
``O&`` (object) [*converter*, *anything*]
654654
Convert *anything* to a Python object through a *converter* function. The
655-
function is called with *anything* (which should be compatible with :c:type:`void
656-
\*`) as its argument and should return a "new" Python object, or ``NULL`` if an
655+
function is called with *anything* (which should be compatible with :c:type:`void*`)
656+
as its argument and should return a "new" Python object, or ``NULL`` if an
657657
error occurred.
658658
659659
``(items)`` (:class:`tuple`) [*matching-items*]

Doc/c-api/buffer.rst

+14-14
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
8989

9090
.. c:type:: Py_buffer
9191
92-
.. c:member:: void \*buf
92+
.. c:member:: void *buf
9393
9494
A pointer to the start of the logical structure described by the buffer
9595
fields. This can be any location within the underlying physical memory
@@ -99,7 +99,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
9999
For :term:`contiguous` arrays, the value points to the beginning of
100100
the memory block.
101101

102-
.. c:member:: void \*obj
102+
.. c:member:: void *obj
103103
104104
A new reference to the exporting object. The reference is owned by
105105
the consumer and automatically decremented and set to ``NULL`` by
@@ -145,7 +145,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
145145
or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard
146146
:c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``.
147147

148-
.. c:member:: const char \*format
148+
.. c:member:: const char *format
149149
150150
A *NUL* terminated string in :mod:`struct` module style syntax describing
151151
the contents of a single item. If this is ``NULL``, ``"B"`` (unsigned bytes)
@@ -164,7 +164,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
164164
to 64. Exporters MUST respect this limit, consumers of multi-dimensional
165165
buffers SHOULD be able to handle up to :c:macro:`PyBUF_MAX_NDIM` dimensions.
166166

167-
.. c:member:: Py_ssize_t \*shape
167+
.. c:member:: Py_ssize_t *shape
168168
169169
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
170170
indicating the shape of the memory as an n-dimensional array. Note that
@@ -177,7 +177,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
177177

178178
The shape array is read-only for the consumer.
179179

180-
.. c:member:: Py_ssize_t \*strides
180+
.. c:member:: Py_ssize_t *strides
181181
182182
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
183183
giving the number of bytes to skip to get to a new element in each
@@ -189,7 +189,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
189189

190190
The strides array is read-only for the consumer.
191191

192-
.. c:member:: Py_ssize_t \*suboffsets
192+
.. c:member:: Py_ssize_t *suboffsets
193193
194194
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`.
195195
If ``suboffsets[n] >= 0``, the values stored along the nth dimension are
@@ -207,7 +207,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
207207

208208
The suboffsets array is read-only for the consumer.
209209

210-
.. c:member:: void \*internal
210+
.. c:member:: void *internal
211211
212212
This is for use internally by the exporting object. For example, this
213213
might be re-cast as an integer by the exporter and used to store flags
@@ -301,7 +301,7 @@ must be C-contiguous.
301301
+-----------------------------------+-------+---------+------------+--------+
302302
| .. c:macro:: PyBUF_ANY_CONTIGUOUS | yes | yes | NULL | C or F |
303303
+-----------------------------------+-------+---------+------------+--------+
304-
| .. c:macro:: PyBUF_ND | yes | NULL | NULL | C |
304+
| :c:macro:`PyBUF_ND` | yes | NULL | NULL | C |
305305
+-----------------------------------+-------+---------+------------+--------+
306306

307307

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

Doc/c-api/capsule.rst

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

Doc/c-api/dict.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ Dictionary Objects
7373
.. index:: single: PyUnicode_FromString()
7474
7575
Insert *val* into the dictionary *p* using *key* as a key. *key* should
76-
be a :c:type:`const char\*`. The key object is created using
76+
be a :c:type:`const char*`. The key object is created using
7777
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
7878
failure. This function *does not* steal a reference to *val*.
7979
@@ -112,7 +112,7 @@ Dictionary Objects
112112
.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
113113
114114
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
115-
:c:type:`const char\*`, rather than a :c:type:`PyObject\*`.
115+
:c:type:`const char*`, rather than a :c:type:`PyObject*`.
116116
117117
Note that exceptions which occur while calling :meth:`__hash__` and
118118
:meth:`__eq__` methods and creating a temporary string object
@@ -161,7 +161,7 @@ Dictionary Objects
161161
prior to the first call to this function to start the iteration; the
162162
function returns true for each pair in the dictionary, and false once all
163163
pairs have been reported. The parameters *pkey* and *pvalue* should either
164-
point to :c:type:`PyObject\*` variables that will be filled in with each key
164+
point to :c:type:`PyObject*` variables that will be filled in with each key
165165
and value, respectively, or may be ``NULL``. Any references returned through
166166
them are borrowed. *ppos* should not be altered during iteration. Its
167167
value represents offsets within the internal dictionary structure, and

Doc/c-api/exceptions.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -771,7 +771,7 @@ Standard Exceptions
771771
772772
All standard Python exceptions are available as global variables whose names are
773773
``PyExc_`` followed by the Python exception name. These have the type
774-
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
774+
:c:type:`PyObject*`; they are all class objects. For completeness, here are all
775775
the variables:
776776
777777
.. index::
@@ -991,7 +991,7 @@ Standard Warning Categories
991991
992992
All standard Python warning categories are available as global variables whose
993993
names are ``PyExc_`` followed by the Python exception name. These have the type
994-
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
994+
:c:type:`PyObject*`; they are all class objects. For completeness, here are all
995995
the variables:
996996
997997
.. index::

Doc/c-api/file.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ File Objects
88
.. index:: object: file
99

1010
These APIs are a minimal emulation of the Python 2 C API for built-in file
11-
objects, which used to rely on the buffered I/O (:c:type:`FILE\*`) support
11+
objects, which used to rely on the buffered I/O (:c:type:`FILE*`) support
1212
from the C standard library. In Python 3, files and streams use the new
1313
:mod:`io` module, which defines several layers over the low-level unbuffered
1414
I/O of the operating system. The functions described below are
@@ -17,7 +17,7 @@ error reporting in the interpreter; third-party code is advised to access
1717
the :mod:`io` APIs instead.
1818

1919

20-
.. c:function:: PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
20+
.. c:function:: PyObject* PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
2121
2222
Create a Python file object from the file descriptor of an already
2323
opened file *fd*. The arguments *name*, *encoding*, *errors* and *newline*

0 commit comments

Comments
 (0)