[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/library/aifc.rst b/Doc/library/aifc.rst
index 7328907..2e917cf 100644
--- a/Doc/library/aifc.rst
+++ b/Doc/library/aifc.rst
@@ -208,6 +208,7 @@
.. method:: aifc.tell()
+ :noindex:
Return the current write position in the output file. Useful in combination
with :meth:`setmark`.
@@ -232,6 +233,7 @@
.. method:: aifc.close()
+ :noindex:
Close the AIFF file. The header of the file is updated to reflect the actual
size of the audio data. After calling this method, the object can no longer be
diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
index 2a3fb14..dc7ae30 100644
--- a/Doc/library/collections.abc.rst
+++ b/Doc/library/collections.abc.rst
@@ -185,7 +185,7 @@
expressions. Custom implementations must provide the :meth:`__await__`
method.
- :term:`Coroutine` objects and instances of the
+ :term:`Coroutine <coroutine>` objects and instances of the
:class:`~collections.abc.Coroutine` ABC are all instances of this ABC.
.. note::
diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst
index b21d559..675a9ff 100644
--- a/Doc/library/concurrent.futures.rst
+++ b/Doc/library/concurrent.futures.rst
@@ -221,7 +221,8 @@
The :class:`ProcessPoolExecutor` class is an :class:`Executor` subclass that
uses a pool of processes to execute calls asynchronously.
:class:`ProcessPoolExecutor` uses the :mod:`multiprocessing` module, which
-allows it to side-step the :term:`Global Interpreter Lock` but also means that
+allows it to side-step the :term:`Global Interpreter Lock
+<global interpreter lock>` but also means that
only picklable objects can be executed and returned.
The ``__main__`` module must be importable by worker subprocesses. This means
diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst
index 739477f..2e22a54 100644
--- a/Doc/library/configparser.rst
+++ b/Doc/library/configparser.rst
@@ -674,97 +674,98 @@
.. attribute:: ConfigParser.BOOLEAN_STATES
- By default when using :meth:`~ConfigParser.getboolean`, config parsers
- consider the following values ``True``: ``'1'``, ``'yes'``, ``'true'``,
- ``'on'`` and the following values ``False``: ``'0'``, ``'no'``, ``'false'``,
- ``'off'``. You can override this by specifying a custom dictionary of strings
- and their Boolean outcomes. For example:
+ By default when using :meth:`~ConfigParser.getboolean`, config parsers
+ consider the following values ``True``: ``'1'``, ``'yes'``, ``'true'``,
+ ``'on'`` and the following values ``False``: ``'0'``, ``'no'``, ``'false'``,
+ ``'off'``. You can override this by specifying a custom dictionary of strings
+ and their Boolean outcomes. For example:
- .. doctest::
+ .. doctest::
- >>> custom = configparser.ConfigParser()
- >>> custom['section1'] = {'funky': 'nope'}
- >>> custom['section1'].getboolean('funky')
- Traceback (most recent call last):
- ...
- ValueError: Not a boolean: nope
- >>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}
- >>> custom['section1'].getboolean('funky')
- False
+ >>> custom = configparser.ConfigParser()
+ >>> custom['section1'] = {'funky': 'nope'}
+ >>> custom['section1'].getboolean('funky')
+ Traceback (most recent call last):
+ ...
+ ValueError: Not a boolean: nope
+ >>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}
+ >>> custom['section1'].getboolean('funky')
+ False
- Other typical Boolean pairs include ``accept``/``reject`` or
- ``enabled``/``disabled``.
+ Other typical Boolean pairs include ``accept``/``reject`` or
+ ``enabled``/``disabled``.
.. method:: ConfigParser.optionxform(option)
+ :noindex:
- This method transforms option names on every read, get, or set
- operation. The default converts the name to lowercase. This also
- means that when a configuration file gets written, all keys will be
- lowercase. Override this method if that's unsuitable.
- For example:
+ This method transforms option names on every read, get, or set
+ operation. The default converts the name to lowercase. This also
+ means that when a configuration file gets written, all keys will be
+ lowercase. Override this method if that's unsuitable.
+ For example:
- .. doctest::
+ .. doctest::
- >>> config = """
- ... [Section1]
- ... Key = Value
- ...
- ... [Section2]
- ... AnotherKey = Value
- ... """
- >>> typical = configparser.ConfigParser()
- >>> typical.read_string(config)
- >>> list(typical['Section1'].keys())
- ['key']
- >>> list(typical['Section2'].keys())
- ['anotherkey']
- >>> custom = configparser.RawConfigParser()
- >>> custom.optionxform = lambda option: option
- >>> custom.read_string(config)
- >>> list(custom['Section1'].keys())
- ['Key']
- >>> list(custom['Section2'].keys())
- ['AnotherKey']
+ >>> config = """
+ ... [Section1]
+ ... Key = Value
+ ...
+ ... [Section2]
+ ... AnotherKey = Value
+ ... """
+ >>> typical = configparser.ConfigParser()
+ >>> typical.read_string(config)
+ >>> list(typical['Section1'].keys())
+ ['key']
+ >>> list(typical['Section2'].keys())
+ ['anotherkey']
+ >>> custom = configparser.RawConfigParser()
+ >>> custom.optionxform = lambda option: option
+ >>> custom.read_string(config)
+ >>> list(custom['Section1'].keys())
+ ['Key']
+ >>> list(custom['Section2'].keys())
+ ['AnotherKey']
- .. note::
- The optionxform function transforms option names to a canonical form.
- This should be an idempotent function: if the name is already in
- canonical form, it should be returned unchanged.
+ .. note::
+ The optionxform function transforms option names to a canonical form.
+ This should be an idempotent function: if the name is already in
+ canonical form, it should be returned unchanged.
.. attribute:: ConfigParser.SECTCRE
- A compiled regular expression used to parse section headers. The default
- matches ``[section]`` to the name ``"section"``. Whitespace is considered
- part of the section name, thus ``[ larch ]`` will be read as a section of
- name ``" larch "``. Override this attribute if that's unsuitable. For
- example:
+ A compiled regular expression used to parse section headers. The default
+ matches ``[section]`` to the name ``"section"``. Whitespace is considered
+ part of the section name, thus ``[ larch ]`` will be read as a section of
+ name ``" larch "``. Override this attribute if that's unsuitable. For
+ example:
- .. doctest::
+ .. doctest::
- >>> import re
- >>> config = """
- ... [Section 1]
- ... option = value
- ...
- ... [ Section 2 ]
- ... another = val
- ... """
- >>> typical = configparser.ConfigParser()
- >>> typical.read_string(config)
- >>> typical.sections()
- ['Section 1', ' Section 2 ']
- >>> custom = configparser.ConfigParser()
- >>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")
- >>> custom.read_string(config)
- >>> custom.sections()
- ['Section 1', 'Section 2']
+ >>> import re
+ >>> config = """
+ ... [Section 1]
+ ... option = value
+ ...
+ ... [ Section 2 ]
+ ... another = val
+ ... """
+ >>> typical = configparser.ConfigParser()
+ >>> typical.read_string(config)
+ >>> typical.sections()
+ ['Section 1', ' Section 2 ']
+ >>> custom = configparser.ConfigParser()
+ >>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")
+ >>> custom.read_string(config)
+ >>> custom.sections()
+ ['Section 1', 'Section 2']
- .. note::
+ .. note::
- While ConfigParser objects also use an ``OPTCRE`` attribute for recognizing
- option lines, it's not recommended to override it because that would
- interfere with constructor options *allow_no_value* and *delimiters*.
+ While ConfigParser objects also use an ``OPTCRE`` attribute for recognizing
+ option lines, it's not recommended to override it because that would
+ interfere with constructor options *allow_no_value* and *delimiters*.
Legacy API Examples
diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst
index 7a898c2..25e3511 100644
--- a/Doc/library/difflib.rst
+++ b/Doc/library/difflib.rst
@@ -24,6 +24,7 @@
.. class:: SequenceMatcher
+ :noindex:
This is a flexible class for comparing pairs of sequences of any type, so long
as the sequence elements are :term:`hashable`. The basic algorithm predates, and is a
@@ -651,6 +652,7 @@
.. class:: Differ(linejunk=None, charjunk=None)
+ :noindex:
Optional keyword parameters *linejunk* and *charjunk* are for filter functions
(or ``None``):
diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index 4b4f5eb..382db11 100644
--- a/Doc/library/enum.rst
+++ b/Doc/library/enum.rst
@@ -50,6 +50,7 @@
the bitwise operations without losing their :class:`Flag` membership.
.. function:: unique
+ :noindex:
Enum class decorator that ensures only one name is bound to any one value.
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index 201f813..b51db9e 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -1070,7 +1070,7 @@
.. class:: WindowsRegistryFinder
- :term:`Finder` for modules declared in the Windows registry. This class
+ :term:`Finder <finder>` for modules declared in the Windows registry. This class
implements the :class:`importlib.abc.MetaPathFinder` ABC.
Only class methods are defined by this class to alleviate the need for
@@ -1085,7 +1085,7 @@
.. class:: PathFinder
- A :term:`Finder` for :data:`sys.path` and package ``__path__`` attributes.
+ A :term:`Finder <finder>` for :data:`sys.path` and package ``__path__`` attributes.
This class implements the :class:`importlib.abc.MetaPathFinder` ABC.
Only class methods are defined by this class to alleviate the need for
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 36c6333..c9992ee 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -14,7 +14,8 @@
:mod:`multiprocessing` is a package that supports spawning processes using an
API similar to the :mod:`threading` module. The :mod:`multiprocessing` package
offers both local and remote concurrency, effectively side-stepping the
-:term:`Global Interpreter Lock` by using subprocesses instead of threads. Due
+:term:`Global Interpreter Lock <global interpreter lock>` by using
+subprocesses instead of threads. Due
to this, the :mod:`multiprocessing` module allows the programmer to fully
leverage multiple processors on a given machine. It runs on both Unix and
Windows.
diff --git a/Doc/library/pkgutil.rst b/Doc/library/pkgutil.rst
index 2066cbb..3b17b9a 100644
--- a/Doc/library/pkgutil.rst
+++ b/Doc/library/pkgutil.rst
@@ -68,7 +68,7 @@
.. class:: ImpLoader(fullname, file, filename, etc)
- :term:`Loader` that wraps Python's "classic" import algorithm.
+ :term:`Loader <loader>` that wraps Python's "classic" import algorithm.
.. deprecated:: 3.3
This emulation is no longer needed, as the standard import mechanism
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index d798c1a..5bcac20 100755
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -1695,7 +1695,9 @@
.. method:: socket.setsockopt(level, optname, value: int)
.. method:: socket.setsockopt(level, optname, value: buffer)
+ :noindex:
.. method:: socket.setsockopt(level, optname, None, optlen: int)
+ :noindex:
.. index:: module: struct
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index fa906f7..62e86d6 100644
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -308,7 +308,7 @@
The general form of a *standard format specifier* is:
-.. productionlist:: sf
+.. productionlist::
format_spec: [[`fill`]`align`][`sign`][#][0][`width`][`grouping_option`][.`precision`][`type`]
fill: <any character>
align: "<" | ">" | "=" | "^"
diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst
index c204263..cca466b 100644
--- a/Doc/library/tarfile.rst
+++ b/Doc/library/tarfile.rst
@@ -151,6 +151,7 @@
.. class:: TarFile
+ :noindex:
Class for reading and writing tar archives. Do not use this class directly:
use :func:`tarfile.open` instead. See :ref:`tarfile-objects`.
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 3a446ad..f4de3c4 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -395,7 +395,8 @@
.. impl-detail::
- In CPython, due to the :term:`Global Interpreter Lock`, only one thread
+ In CPython, due to the :term:`Global Interpreter Lock
+ <global interpreter lock>`, only one thread
can execute Python code at once (even though certain performance-oriented
libraries might overcome this limitation).
If you want your application to make better use of the computational
diff --git a/Doc/library/token.rst b/Doc/library/token.rst
index dab8f0f..7f598cd 100644
--- a/Doc/library/token.rst
+++ b/Doc/library/token.rst
@@ -70,6 +70,7 @@
.. data:: TYPE_COMMENT
+ :noindex:
Token value indicating that a type comment was recognized. Such
tokens are only produced when :func:`ast.parse()` is invoked with
diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst
index fed8504..d348753 100644
--- a/Doc/library/turtle.rst
+++ b/Doc/library/turtle.rst
@@ -1069,6 +1069,7 @@
~~~~~~~~~~~~~~~~~~~~
.. function:: reset()
+ :noindex:
Delete the turtle's drawings from the screen, re-center the turtle and set
variables to the default values.
@@ -1090,6 +1091,7 @@
.. function:: clear()
+ :noindex:
Delete the turtle's drawings from the screen. Do not move turtle. State and
position of the turtle as well as drawings of other turtles are not affected.
@@ -1362,6 +1364,7 @@
------------
.. function:: onclick(fun, btn=1, add=None)
+ :noindex:
:param fun: a function with two arguments which will be called with the
coordinates of the clicked point on the canvas
diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
index 03712c1..785ecf8 100644
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -946,7 +946,7 @@
If *is_authenticated* is specified as ``True``, *realm* is ignored.
-.. method:: HTTPPasswordMgr.find_user_password(realm, authuri)
+.. method:: HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri)
Same as for :class:`HTTPPasswordMgrWithDefaultRealm` objects