[Python-checkins] bpo-40204: Fix reference to terms in the doc (GH-21865)

Victor Stinner webhook-mailer at python.org
Fri Aug 14 06:20:37 EDT 2020

commit: bb0b08540cc93e56f3f1bde1b39ce086d9e35fe1
branch: master
author: Victor Stinner <vstinner at python.org>
committer: GitHub <noreply at github.com>
date: 2020-08-14T12:20:05+02:00

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.

M Doc/extending/newtypes_tutorial.rst
M Doc/glossary.rst
M Doc/library/collections.abc.rst
M Doc/library/concurrent.futures.rst
M Doc/library/importlib.rst
M Doc/library/multiprocessing.rst
M Doc/library/pkgutil.rst
M Doc/library/threading.rst
M Doc/reference/datamodel.rst
M Doc/tutorial/classes.rst
M Doc/whatsnew/3.2.rst
M Doc/whatsnew/3.5.rst
M Doc/whatsnew/3.6.rst
M Doc/whatsnew/3.7.rst

diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst
index 0eb6ffd026f49..4da77e797d222 100644
--- a/Doc/extending/newtypes_tutorial.rst
+++ b/Doc/extending/newtypes_tutorial.rst
@@ -416,7 +416,7 @@ But this would be risky.  Our type doesn't restrict the type of the
 ``first`` member, so it could be any kind of object.  It could have a
 destructor that causes code to be executed that tries to access the
 ``first`` member; or that destructor could release the
-:term:`Global interpreter Lock` and let arbitrary code run in other
+:term:`Global interpreter Lock <GIL>` and let arbitrary code run in other
 threads that accesses and modifies our object.
 To be paranoid and protect ourselves against this possibility, we almost
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index e997d366777b3..7be755e411310 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -587,7 +587,7 @@ Glossary
       and :class:`tuple`) and some non-sequence types like :class:`dict`,
       :term:`file objects <file object>`, and objects of any classes you define
       with an :meth:`__iter__` method or with a :meth:`__getitem__` method
-      that implements :term:`Sequence` semantics.
+      that implements :term:`Sequence <sequence>` semantics.
       Iterables can be
       used in a :keyword:`for` loop and in many other places where a sequence is
diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
index 2a3fb142f7297..dc7ae30b6d2fa 100644
--- a/Doc/library/collections.abc.rst
+++ b/Doc/library/collections.abc.rst
@@ -185,7 +185,7 @@ ABC                        Inherits from          Abstract Methods        Mixin
    expressions.  Custom implementations must provide the :meth:`__await__`
-   :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 b21d5594c84fa..675a9ffdd0711 100644
--- a/Doc/library/concurrent.futures.rst
+++ b/Doc/library/concurrent.futures.rst
@@ -221,7 +221,8 @@ ProcessPoolExecutor
 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/importlib.rst b/Doc/library/importlib.rst
index f7286d2ade8bd..5fb0a4a120b98 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -1073,7 +1073,7 @@ find and load modules.
 .. 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
@@ -1088,7 +1088,7 @@ find and load modules.
 .. 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 69d6523650386..28510acd52bd4 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -14,7 +14,8 @@ Introduction
 :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
diff --git a/Doc/library/pkgutil.rst b/Doc/library/pkgutil.rst
index 2066cbb9fc57c..3b17b9a621987 100644
--- a/Doc/library/pkgutil.rst
+++ b/Doc/library/pkgutil.rst
@@ -68,7 +68,7 @@ support.
 .. 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/threading.rst b/Doc/library/threading.rst
index 458e39bf721c6..7fcf93d74610e 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -394,7 +394,8 @@ since it is impossible to detect the termination of alien threads.
 .. 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/reference/datamodel.rst b/Doc/reference/datamodel.rst
index c5a7f046992dd..a817408c3b1ef 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -2601,7 +2601,7 @@ Awaitable Objects
 An :term:`awaitable` object generally implements an :meth:`__await__` method.
-:term:`Coroutine` objects returned from :keyword:`async def` functions
+:term:`Coroutine objects <coroutine>` returned from :keyword:`async def` functions
 are awaitable.
 .. note::
@@ -2626,7 +2626,7 @@ are awaitable.
 Coroutine Objects
-:term:`Coroutine` objects are :term:`awaitable` objects.
+:term:`Coroutine objects <coroutine>` are :term:`awaitable` objects.
 A coroutine's execution can be controlled by calling :meth:`__await__` and
 iterating over the result.  When the coroutine has finished executing and
 returns, the iterator raises :exc:`StopIteration`, and the exception's
diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst
index 685552f99f440..0d780e3ba8964 100644
--- a/Doc/tutorial/classes.rst
+++ b/Doc/tutorial/classes.rst
@@ -849,7 +849,7 @@ defines :meth:`__next__`, then :meth:`__iter__` can just return ``self``::
-:term:`Generator`\s are a simple and powerful tool for creating iterators.  They
+:term:`Generators <generator>` are a simple and powerful tool for creating iterators.  They
 are written like regular functions but use the :keyword:`yield` statement
 whenever they want to return data.  Each time :func:`next` is called on it, the
 generator resumes where it left off (it remembers all the data values and which
diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst
index ca3eda05c515a..06bee9966c0be 100644
--- a/Doc/whatsnew/3.2.rst
+++ b/Doc/whatsnew/3.2.rst
@@ -2311,7 +2311,7 @@ Multi-threading
 * The mechanism for serializing execution of concurrently running Python threads
-  (generally known as the :term:`GIL` or :term:`Global Interpreter Lock`) has
+  (generally known as the :term:`GIL` or Global Interpreter Lock) has
   been rewritten.  Among the objectives were more predictable switching
   intervals and reduced overhead due to lock contention and the number of
   ensuing system calls.  The notion of a "check interval" to allow thread
diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst
index b4540ac1dd902..1defee4090f28 100644
--- a/Doc/whatsnew/3.5.rst
+++ b/Doc/whatsnew/3.5.rst
@@ -412,7 +412,7 @@ uses were to provide type hints to function parameters and return values.  It
 became evident that it would be beneficial for Python users, if the
 standard library included the base definitions and tools for type annotations.
-:pep:`484` introduces a :term:`provisional module <provisional api>` to
+:pep:`484` introduces a :term:`provisional module <provisional API>` to
 provide these standard definitions and tools, along with some conventions
 for situations where annotations are not available.
@@ -726,7 +726,7 @@ New Modules
-The new :mod:`typing` :term:`provisional <provisional api>` module
+The new :mod:`typing` :term:`provisional <provisional API>` module
 provides standard definitions and tools for function type annotations.
 See :ref:`Type Hints <whatsnew-pep-484>` for more information.
@@ -772,7 +772,7 @@ Steven Bethard, paul j3 and Daniel Eriksson in :issue:`14910`.)
-Since the :mod:`asyncio` module is :term:`provisional <provisional api>`,
+Since the :mod:`asyncio` module is :term:`provisional <provisional API>`,
 all changes introduced in Python 3.5 have also been backported to Python 3.4.x.
 Notable changes in the :mod:`asyncio` module since Python 3.4.0:
@@ -1867,7 +1867,7 @@ A new :func:`~sys.set_coroutine_wrapper` function allows setting a global
 hook that will be called whenever a :term:`coroutine object <coroutine>`
 is created by an :keyword:`async def` function.  A corresponding
 :func:`~sys.get_coroutine_wrapper` can be used to obtain a currently set
-wrapper.  Both functions are :term:`provisional <provisional api>`,
+wrapper.  Both functions are :term:`provisional <provisional API>`,
 and are intended for debugging purposes only.  (Contributed by Yury Selivanov
 in :issue:`24017`.)
diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst
index 04c1f7e71db32..85a6657fdfbda 100644
--- a/Doc/whatsnew/3.6.rst
+++ b/Doc/whatsnew/3.6.rst
@@ -1597,7 +1597,7 @@ to filter block traces by their address space (domain).
-Since the :mod:`typing` module is :term:`provisional <provisional api>`,
+Since the :mod:`typing` module is :term:`provisional <provisional API>`,
 all changes introduced in Python 3.6 have also been
 backported to Python 3.5.x.
diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst
index 279bbc697b5c6..25b1e1e33e325 100644
--- a/Doc/whatsnew/3.7.rst
+++ b/Doc/whatsnew/3.7.rst
@@ -636,7 +636,7 @@ The :mod:`asyncio` module has received many new features, usability and
 :ref:`performance improvements <whatsnew37-asyncio-perf>`.  Notable changes
-* The new :term:`provisional <provisional api>` :func:`asyncio.run` function can
+* The new :term:`provisional <provisional API>` :func:`asyncio.run` function can
   be used to run a coroutine from synchronous code by automatically creating and
   destroying the event loop.
   (Contributed by Yury Selivanov in :issue:`32314`.)

More information about the Python-checkins mailing list