[3.9] bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844) (GH-21901)
* bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-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 423e77d6de497931585d1883805a9e3fa4096b0b)
* bpo-40204: Fix Sphinx sytanx in howto/instrumentation.rst (GH-21858)
Use generic '.. object::' to declare markers, rather than abusing
'.. c:function::' which fails on Sphinx 3.
(cherry picked from commit 43577c01a2ab49122db696e9eaec6cb31d11cc81)
* bpo-40204: Fix duplicates in the documentation (GH-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 46d10b1237c67ff8347f533eda6a5468d098f7eb)
* bpo-40204: Add :noindex: in the documentation (GH-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 d3ded080482beae578faa704b13534a62d066f9f)
* bpo-40204, doc: Fix syntax of C variables (GH-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 474652fe9346382dbf793f20b671eb74668bebde)
* bpo-40204: Fix reference to terms in the doc (GH-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 bb0b08540cc93e56f3f1bde1b39ce086d9e35fe1)
* bpo-40204: Fix duplicated productionlist names in the doc (GH-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 1abeda80f760134b4233608e2c288790f955b95a)
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 68fed2a..7f06648 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -81,7 +81,7 @@
that the option was set. For example, ``-b`` sets :c:data:`Py_BytesWarningFlag`
to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
-.. c:var:: Py_BytesWarningFlag
+.. c:var:: int Py_BytesWarningFlag
Issue a warning when comparing :class:`bytes` or :class:`bytearray` with
:class:`str` or :class:`bytes` with :class:`int`. Issue an error if greater
@@ -89,7 +89,7 @@
Set by the :option:`-b` option.
-.. c:var:: Py_DebugFlag
+.. c:var:: int Py_DebugFlag
Turn on parser debugging output (for expert only, depending on compilation
options).
@@ -97,7 +97,7 @@
Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment
variable.
-.. c:var:: Py_DontWriteBytecodeFlag
+.. c:var:: int Py_DontWriteBytecodeFlag
If set to non-zero, Python won't try to write ``.pyc`` files on the
import of source modules.
@@ -105,14 +105,14 @@
Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE`
environment variable.
-.. c:var:: Py_FrozenFlag
+.. c:var:: int Py_FrozenFlag
Suppress error messages when calculating the module search path in
:c:func:`Py_GetPath`.
Private flag used by ``_freeze_importlib`` and ``frozenmain`` programs.
-.. c:var:: Py_HashRandomizationFlag
+.. c:var:: int Py_HashRandomizationFlag
Set to ``1`` if the :envvar:`PYTHONHASHSEED` environment variable is set to
a non-empty string.
@@ -120,14 +120,14 @@
If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment
variable to initialize the secret hash seed.
-.. c:var:: Py_IgnoreEnvironmentFlag
+.. c:var:: int Py_IgnoreEnvironmentFlag
Ignore all :envvar:`PYTHON*` environment variables, e.g.
:envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
Set by the :option:`-E` and :option:`-I` options.
-.. c:var:: Py_InspectFlag
+.. c:var:: int Py_InspectFlag
When a script is passed as first argument or the :option:`-c` option is used,
enter interactive mode after executing the script or the command, even when
@@ -136,11 +136,11 @@
Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment
variable.
-.. c:var:: Py_InteractiveFlag
+.. c:var:: int Py_InteractiveFlag
Set by the :option:`-i` option.
-.. c:var:: Py_IsolatedFlag
+.. c:var:: int Py_IsolatedFlag
Run Python in isolated mode. In isolated mode :data:`sys.path` contains
neither the script's directory nor the user's site-packages directory.
@@ -149,7 +149,7 @@
.. versionadded:: 3.4
-.. c:var:: Py_LegacyWindowsFSEncodingFlag
+.. c:var:: int Py_LegacyWindowsFSEncodingFlag
If the flag is non-zero, use the ``mbcs`` encoding instead of the UTF-8
encoding for the filesystem encoding.
@@ -161,7 +161,7 @@
.. availability:: Windows.
-.. c:var:: Py_LegacyWindowsStdioFlag
+.. c:var:: int Py_LegacyWindowsStdioFlag
If the flag is non-zero, use :class:`io.FileIO` instead of
:class:`WindowsConsoleIO` for :mod:`sys` standard streams.
@@ -173,7 +173,7 @@
.. availability:: Windows.
-.. c:var:: Py_NoSiteFlag
+.. c:var:: int Py_NoSiteFlag
Disable the import of the module :mod:`site` and the site-dependent
manipulations of :data:`sys.path` that it entails. Also disable these
@@ -182,7 +182,7 @@
Set by the :option:`-S` option.
-.. c:var:: Py_NoUserSiteDirectory
+.. c:var:: int Py_NoUserSiteDirectory
Don't add the :data:`user site-packages directory <site.USER_SITE>` to
:data:`sys.path`.
@@ -190,12 +190,12 @@
Set by the :option:`-s` and :option:`-I` options, and the
:envvar:`PYTHONNOUSERSITE` environment variable.
-.. c:var:: Py_OptimizeFlag
+.. c:var:: int Py_OptimizeFlag
Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment
variable.
-.. c:var:: Py_QuietFlag
+.. c:var:: int Py_QuietFlag
Don't display the copyright and version messages even in interactive mode.
@@ -203,14 +203,14 @@
.. versionadded:: 3.2
-.. c:var:: Py_UnbufferedStdioFlag
+.. c:var:: int Py_UnbufferedStdioFlag
Force the stdout and stderr streams to be unbuffered.
Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED`
environment variable.
-.. c:var:: Py_VerboseFlag
+.. c:var:: int Py_VerboseFlag
Print a message each time a module is initialized, showing the place
(filename or built-in module) from which it is loaded. If greater or equal
@@ -830,7 +830,7 @@
.. c:type:: PyThreadState
This data structure represents the state of a single thread. The only public
- data member is :c:type:`PyInterpreterState \*`:attr:`interp`, which points to
+ data member is :attr:`interp` (:c:type:`PyInterpreterState *`), which points to
this thread's interpreter state.
@@ -1619,7 +1619,7 @@
(TLS) which wraps the underlying native TLS implementation to support the
Python-level thread local storage API (:class:`threading.local`). The
CPython C level APIs are similar to those offered by pthreads and Windows:
-use a thread key and functions to associate a :c:type:`void\*` value per
+use a thread key and functions to associate a :c:type:`void*` value per
thread.
The GIL does *not* need to be held when calling these functions; they supply
@@ -1630,8 +1630,8 @@
.. note::
None of these API functions handle memory management on behalf of the
- :c:type:`void\*` values. You need to allocate and deallocate them yourself.
- If the :c:type:`void\*` values happen to be :c:type:`PyObject\*`, these
+ :c:type:`void*` values. You need to allocate and deallocate them yourself.
+ If the :c:type:`void*` values happen to be :c:type:`PyObject*`, these
functions don't do refcount operations on them either.
.. _thread-specific-storage-api:
@@ -1727,14 +1727,14 @@
.. c:function:: int PyThread_tss_set(Py_tss_t *key, void *value)
- Return a zero value to indicate successfully associating a :c:type:`void\*`
+ Return a zero value to indicate successfully associating a :c:type:`void*`
value with a TSS key in the current thread. Each thread has a distinct
- mapping of the key to a :c:type:`void\*` value.
+ mapping of the key to a :c:type:`void*` value.
.. c:function:: void* PyThread_tss_get(Py_tss_t *key)
- Return the :c:type:`void\*` value associated with a TSS key in the current
+ Return the :c:type:`void*` value associated with a TSS key in the current
thread. This returns ``NULL`` if no value is associated with the key in the
current thread.