[3.12] gh-101100: Fix Sphinx warnings in whatsnew/2.1.rst (GH-112357) (#115932)

miss-islington · hugovk · terryjreedy · web-flow · commit 551e12f893b5 · 2024-02-26T06:55:23.000Z
Co-authored-by: Hugo van Kemenade &lt;1324225+hugovk@users.noreply.github.com&gt;
Co-authored-by: Terry Jan Reedy &lt;tjreedy@udel.edu&gt;
Co-authored-by: Hugo van Kemenade &lt;hugovk@users.noreply.github.com&gt;
diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
@@ -95,7 +95,6 @@ Doc/reference/compound_stmts.rst
 Doc/reference/datamodel.rst
 Doc/tutorial/datastructures.rst
 Doc/using/windows.rst
-Doc/whatsnew/2.1.rst
 Doc/whatsnew/2.4.rst
 Doc/whatsnew/2.5.rst
 Doc/whatsnew/2.6.rst
diff --git a/Doc/whatsnew/2.1.rst b/Doc/whatsnew/2.1.rst
@@ -48,7 +48,7 @@ nested recursive function definition doesn't work::
            return g(value-1) + 1
        ...
 
-The function :func:`g` will always raise a :exc:`NameError` exception, because
+The function :func:`!g` will always raise a :exc:`NameError` exception, because
 the binding of the name ``g`` isn't in either its local namespace or in the
 module-level namespace.  This isn't much of a problem in practice (how often do
 you recursively define interior functions like this?), but this also made using
@@ -104,7 +104,7 @@ To make the preceding explanation a bit clearer, here's an example::
 
 Line 4 containing the ``exec`` statement is a syntax error, since
 ``exec`` would define a new local variable named ``x`` whose value should
-be accessed by :func:`g`.
+be accessed by :func:`!g`.
 
 This shouldn't be much of a limitation, since ``exec`` is rarely used in
 most Python code (and when it is used, it's often a sign of a poor design
@@ -161,7 +161,7 @@ PEP 207: Rich Comparisons
 
 In earlier versions, Python's support for implementing comparisons on user-defined
 classes and extension types was quite simple. Classes could implement a
-:meth:`__cmp__` method that was given two instances of a class, and could only
+:meth:`!__cmp__` method that was given two instances of a class, and could only
 return 0 if they were equal or +1 or -1 if they weren't; the method couldn't
 raise an exception or return anything other than a Boolean value.  Users of
 Numeric Python often found this model too weak and restrictive, because in the
@@ -175,21 +175,21 @@ In Python 2.1, rich comparisons were added in order to support this need.
 Python classes can now individually overload each of the ``<``, ``<=``, ``>``,
 ``>=``, ``==``, and ``!=`` operations.  The new magic method names are:
 
-+-----------+----------------+
-| Operation | Method name    |
-+===========+================+
-| ``<``     | :meth:`__lt__` |
-+-----------+----------------+
-| ``<=``    | :meth:`__le__` |
-+-----------+----------------+
-| ``>``     | :meth:`__gt__` |
-+-----------+----------------+
-| ``>=``    | :meth:`__ge__` |
-+-----------+----------------+
-| ``==``    | :meth:`__eq__` |
-+-----------+----------------+
-| ``!=``    | :meth:`__ne__` |
-+-----------+----------------+
++-----------+------------------------+
+| Operation | Method name            |
++===========+========================+
+| ``<``     | :meth:`~object.__lt__` |
++-----------+------------------------+
+| ``<=``    | :meth:`~object.__le__` |
++-----------+------------------------+
+| ``>``     | :meth:`~object.__gt__` |
++-----------+------------------------+
+| ``>=``    | :meth:`~object.__ge__` |
++-----------+------------------------+
+| ``==``    | :meth:`~object.__eq__` |
++-----------+------------------------+
+| ``!=``    | :meth:`~object.__ne__` |
++-----------+------------------------+
 
 (The magic methods are named after the corresponding Fortran operators ``.LT.``.
 ``.LE.``, &c.  Numeric programmers are almost certainly quite familiar with
@@ -208,7 +208,7 @@ The built-in ``cmp(A,B)`` function can use the rich comparison machinery,
 and now accepts an optional argument specifying which comparison operation to
 use; this is given as one of the strings ``"<"``, ``"<="``, ``">"``, ``">="``,
 ``"=="``, or ``"!="``.  If called without the optional third argument,
-:func:`cmp` will only return -1, 0, or +1 as in previous versions of Python;
+:func:`!cmp` will only return -1, 0, or +1 as in previous versions of Python;
 otherwise it will call the appropriate method and can return any Python object.
 
 There are also corresponding changes of interest to C programmers; there's a new
@@ -245,7 +245,7 @@ out warnings that you don't want to be displayed. Third-party modules can also
 use this framework to deprecate old features that they no longer wish to
 support.
 
-For example, in Python 2.1 the :mod:`regex` module is deprecated, so importing
+For example, in Python 2.1 the :mod:`!regex` module is deprecated, so importing
 it causes a warning to be printed::
 
    >>> import regex
@@ -262,7 +262,7 @@ can be used to specify a particular warning category.
 
 Filters can be added to disable certain warnings; a regular expression pattern
 can be applied to the message or to the module name in order to suppress a
-warning.  For example, you may have a program that uses the :mod:`regex` module
+warning.  For example, you may have a program that uses the :mod:`!regex` module
 and not want to spare the time to convert it to use the :mod:`re` module right
 now.  The warning can be suppressed by calling ::
 
@@ -274,7 +274,7 @@ now.  The warning can be suppressed by calling ::
 
 This adds a filter that will apply only to warnings of the class
 :class:`DeprecationWarning` triggered in the :mod:`__main__` module, and applies
-a regular expression to only match the message about the :mod:`regex` module
+a regular expression to only match the message about the :mod:`!regex` module
 being deprecated, and will cause such warnings to be ignored.  Warnings can also
 be printed only once, printed every time the offending code is executed, or
 turned into exceptions that will cause the program to stop (unless the
@@ -368,7 +368,7 @@ dictionary::
 This version works for simple things such as integers, but it has a side effect;
 the ``_cache`` dictionary holds a reference to the return values, so they'll
 never be deallocated until the Python process exits and cleans up. This isn't
-very noticeable for integers, but if :func:`f` returns an object, or a data
+very noticeable for integers, but if :func:`!f` returns an object, or a data
 structure that takes up a lot of memory, this can be a problem.
 
 Weak references provide a way to implement a cache that won't keep objects alive
@@ -379,7 +379,7 @@ created by calling ``wr = weakref.ref(obj)``.  The object being referred to is
 returned by calling the weak reference as if it were a function: ``wr()``.  It
 will return the referenced object, or ``None`` if the object no longer exists.
 
-This makes it possible to write a :func:`memoize` function whose cache doesn't
+This makes it possible to write a :func:`!memoize` function whose cache doesn't
 keep objects alive, by storing weak references in the cache. ::
 
    _cache = {}
@@ -402,7 +402,7 @@ weak references --- an object referenced only by proxy objects is deallocated --
 but instead of requiring an explicit call to retrieve the object, the proxy
 transparently forwards all operations to the object as long as the object still
 exists.  If the object is deallocated, attempting to use a proxy will cause a
-:exc:`weakref.ReferenceError` exception to be raised. ::
+:exc:`!weakref.ReferenceError` exception to be raised. ::
 
    proxy = weakref.proxy(obj)
    proxy.attr   # Equivalent to obj.attr
@@ -446,7 +446,7 @@ The dictionary containing attributes can be accessed as the function's
 :attr:`~object.__dict__`. Unlike the :attr:`~object.__dict__` attribute of class instances, in
 functions you can actually assign a new dictionary to :attr:`~object.__dict__`, though
 the new value is restricted to a regular Python dictionary; you *can't* be
-tricky and set it to a :class:`UserDict` instance, or any other random object
+tricky and set it to a :class:`!UserDict` instance, or any other random object
 that behaves like a mapping.
 
 
@@ -584,11 +584,11 @@ available from the Distutils SIG at https://www.python.org/community/sigs/curren
 New and Improved Modules
 ========================
 
-* Ka-Ping Yee contributed two new modules: :mod:`inspect.py`, a module for
-  getting information about live Python code, and :mod:`pydoc.py`, a module for
+* Ka-Ping Yee contributed two new modules: :mod:`!inspect.py`, a module for
+  getting information about live Python code, and :mod:`!pydoc.py`, a module for
   interactively converting docstrings to HTML or text.  As a bonus,
   :file:`Tools/scripts/pydoc`, which is now automatically installed, uses
-  :mod:`pydoc.py` to display documentation given a Python module, package, or
+  :mod:`!pydoc.py` to display documentation given a Python module, package, or
   class name.  For example, ``pydoc xml.dom`` displays the following::
 
      Python Library Documentation: package xml.dom in xml
@@ -617,7 +617,7 @@ New and Improved Modules
   Kent Beck's Smalltalk testing framework.  See https://pyunit.sourceforge.net/ for
   more information about PyUnit.
 
-* The :mod:`difflib` module contains a class, :class:`SequenceMatcher`, which
+* The :mod:`difflib` module contains a class, :class:`~difflib.SequenceMatcher`, which
   compares two sequences and computes the changes required to transform one
   sequence into the other.  For example, this module can be used to write a tool
   similar to the Unix :program:`diff` program, and in fact the sample program
@@ -633,7 +633,7 @@ New and Improved Modules
   2.1 includes an updated version of the :mod:`xml` package.  Some of the
   noteworthy changes include support for Expat 1.2 and later versions, the ability
   for Expat parsers to handle files in any encoding supported by Python, and
-  various bugfixes for SAX, DOM, and the :mod:`minidom` module.
+  various bugfixes for SAX, DOM, and the :mod:`!minidom` module.
 
 * Ping also contributed another hook for handling uncaught exceptions.
   :func:`sys.excepthook` can be set to a callable object.  When an exception isn't
@@ -643,8 +643,8 @@ New and Improved Modules
   printing an extended traceback that not only lists the stack frames, but also
   lists the function arguments and the local variables for each frame.
 
-* Various functions in the :mod:`time` module, such as :func:`asctime` and
-  :func:`localtime`, require a floating point argument containing the time in
+* Various functions in the :mod:`time` module, such as :func:`~time.asctime` and
+  :func:`~time.localtime`, require a floating point argument containing the time in
   seconds since the epoch.  The most common use of these functions is to work with
   the current time, so the floating point argument has been made optional; when a
   value isn't provided, the current time will be used.  For example, log file
@@ -724,10 +724,10 @@ of the more notable changes are:
   a discussion in comp.lang.python.
 
   A new module and method for file objects was also added, contributed by Jeff
-  Epler. The new method, :meth:`xreadlines`, is similar to the existing
-  :func:`xrange` built-in.  :func:`xreadlines` returns an opaque sequence object
+  Epler. The new method, :meth:`!xreadlines`, is similar to the existing
+  :func:`!xrange` built-in.  :func:`!xreadlines` returns an opaque sequence object
   that only supports being iterated over, reading a line on every iteration but
-  not reading the entire file into memory as the existing :meth:`readlines` method
+  not reading the entire file into memory as the existing :meth:`!readlines` method
   does. You'd use it like this::
 
      for line in sys.stdin.xreadlines():
@@ -737,7 +737,7 @@ of the more notable changes are:
   For a fuller discussion of the line I/O changes, see the python-dev summary for
   January 1--15, 2001 at https://mail.python.org/pipermail/python-dev/2001-January/.
 
-* A new method, :meth:`popitem`, was added to dictionaries to enable
+* A new method, :meth:`~dict.popitem`, was added to dictionaries to enable
   destructively iterating through the contents of a dictionary; this can be faster
   for large dictionaries because there's no need to construct a list containing
   all the keys or values. ``D.popitem()`` removes a random ``(key, value)`` pair
