[Python-checkins] gh-71223: Improve rendering of some references in the docs (GH-93041)

miss-islington webhook-mailer at python.org
Sat May 21 03:49:45 EDT 2022


https://github.com/python/cpython/commit/f2aeb3f6f782716d6b8fbff336d6258a24ba021c
commit: f2aeb3f6f782716d6b8fbff336d6258a24ba021c
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-05-21T00:49:36-07:00
summary:

gh-71223: Improve rendering of some references in the docs (GH-93041)


For example, instead of "eval()uated" (link from "eval()")
show "evaluated" (link from the whole word).
(cherry picked from commit 7f835923c179d1d2da54b232e0113abc2c56ea31)

Co-authored-by: Serhiy Storchaka <storchaka at gmail.com>

files:
M Doc/library/email.headerregistry.rst
M Doc/library/functions.rst
M Doc/library/logging.config.rst
M Doc/library/stdtypes.rst
M Doc/library/threading.rst
M Doc/library/weakref.rst
M Doc/whatsnew/3.4.rst

diff --git a/Doc/library/email.headerregistry.rst b/Doc/library/email.headerregistry.rst
index 3e1d97a03264b..98527cea43da2 100644
--- a/Doc/library/email.headerregistry.rst
+++ b/Doc/library/email.headerregistry.rst
@@ -206,7 +206,7 @@ headers.
 
    The ``decoded`` value of the header will have all encoded words decoded to
    unicode.  :class:`~encodings.idna` encoded domain names are also decoded to
-   unicode.  The ``decoded`` value is set by :attr:`~str.join`\ ing the
+   unicode.  The ``decoded`` value is set by :ref:`joining <meth-str-join>` the
    :class:`str` value of the elements of the ``groups`` attribute with ``',
    '``.
 
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 92b2c3bb53944..f5e4c1a8640f4 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -500,6 +500,7 @@ are always available.  They are listed here in alphabetical order.
               yield n, elem
               n += 1
 
+.. _func-eval:
 
 .. function:: eval(expression[, globals[, locals]])
 
diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst
index 2f105ba29441d..310796e7ac6b1 100644
--- a/Doc/library/logging.config.rst
+++ b/Doc/library/logging.config.rst
@@ -716,7 +716,7 @@ root logger section is given below.
 
 The ``level`` entry can be one of ``DEBUG, INFO, WARNING, ERROR, CRITICAL`` or
 ``NOTSET``. For the root logger only, ``NOTSET`` means that all messages will be
-logged. Level values are :func:`eval`\ uated in the context of the ``logging``
+logged. Level values are :ref:`evaluated <func-eval>` in the context of the ``logging``
 package's namespace.
 
 The ``handlers`` entry is a comma-separated list of handler names, which must
@@ -763,13 +763,13 @@ handler. If blank, a default formatter (``logging._defaultFormatter``) is used.
 If a name is specified, it must appear in the ``[formatters]`` section and have
 a corresponding section in the configuration file.
 
-The ``args`` entry, when :func:`eval`\ uated in the context of the ``logging``
+The ``args`` entry, when :ref:`evaluated <func-eval>` in the context of the ``logging``
 package's namespace, is the list of arguments to the constructor for the handler
 class. Refer to the constructors for the relevant handlers, or to the examples
 below, to see how typical entries are constructed. If not provided, it defaults
 to ``()``.
 
-The optional ``kwargs`` entry, when :func:`eval`\ uated in the context of the
+The optional ``kwargs`` entry, when :ref:`evaluated <func-eval>` in the context of the
 ``logging`` package's namespace, is the keyword argument dict to the constructor
 for the handler class. If not provided, it defaults to ``{}``.
 
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 065afb8ae6038..33fd2831228f8 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1866,6 +1866,8 @@ expression support in the :mod:`re` module).
 
 
 
+.. _meth-str-join:
+
 .. method:: str.join(iterable)
 
    Return a string which is the concatenation of the strings in *iterable*.
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index b777560961690..e654dedfd91a2 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -293,7 +293,7 @@ There is the possibility that "dummy thread objects" are created. These are
 thread objects corresponding to "alien threads", which are threads of control
 started outside the threading module, such as directly from C code.  Dummy
 thread objects have limited functionality; they are always considered alive and
-daemonic, and cannot be :meth:`~Thread.join`\ ed.  They are never deleted,
+daemonic, and cannot be :ref:`joined <meth-thread-join>`.  They are never deleted,
 since it is impossible to detect the termination of alien threads.
 
 
@@ -366,6 +366,8 @@ since it is impossible to detect the termination of alien threads.
          >>> t.run()
          1
 
+   .. _meth-thread-join:
+
    .. method:: join(timeout=None)
 
       Wait until the thread terminates. This blocks the calling thread until
@@ -383,7 +385,7 @@ since it is impossible to detect the termination of alien threads.
       When the *timeout* argument is not present or ``None``, the operation will
       block until the thread terminates.
 
-      A thread can be :meth:`~Thread.join`\ ed many times.
+      A thread can be joined many times.
 
       :meth:`~Thread.join` raises a :exc:`RuntimeError` if an attempt is made
       to join the current thread as that would cause a deadlock. It is also
diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst
index 1102c634edaf3..8397de4fb488f 100644
--- a/Doc/library/weakref.rst
+++ b/Doc/library/weakref.rst
@@ -1,3 +1,5 @@
+.. _mod-weakref:
+
 :mod:`weakref` --- Weak references
 ==================================
 
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
index f4ff143224196..023736134b2ca 100644
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -409,7 +409,7 @@ Some smaller changes made to the core Python language are:
   evaluating has no elements.  (Contributed by Julian Berman in
   :issue:`18111`.)
 
-* Module objects are now :mod:`weakref`'able.
+* Module objects are now :ref:`weakly referenceable <mod-weakref>`.
 
 * Module ``__file__`` attributes (and related values) should now always
   contain absolute paths by default, with the sole exception of
@@ -1113,8 +1113,8 @@ with additional speedups by Antoine Pitrou in :issue:`19219`.)
 mmap
 ----
 
-mmap objects can now be :mod:`weakref`\ ed.  (Contributed by Valerie Lambert in
-:issue:`4885`.)
+mmap objects are now :ref:`weakly referenceable <mod-weakref>`.
+(Contributed by Valerie Lambert in :issue:`4885`.)
 
 
 multiprocessing



More information about the Python-checkins mailing list