pythongh-101100: Fix Sphinx warnings from PEP 3108 stdlib re-organisation (python#114327)

* Fix Sphinx warnings from PEP 3108 stdblib re-organisation

* Apply suggestions from code review

Co-authored-by: Alex Waygood <[email protected]>

* Update Doc/whatsnew/2.2.rst

Co-authored-by: Alex Waygood <[email protected]>

* Apply suggestions from code review

Co-authored-by: Alex Waygood <[email protected]>

---------

Co-authored-by: Alex Waygood <[email protected]>

Author: hugovk

Doc/whatsnew/2.0.rst

@@ -1039,12 +1039,12 @@ is an implementation of the Secure Socket Layer, which encrypts the data being
 sent over a socket.  When compiling Python, you can edit :file:`Modules/Setup`
 to include SSL support, which adds an additional function to the :mod:`socket`
 module: ``socket.ssl(socket, keyfile, certfile)``, which takes a socket
-object and returns an SSL socket.  The :mod:`httplib` and :mod:`urllib` modules
+object and returns an SSL socket.  The :mod:`httplib <http>` and :mod:`urllib` modules
 were also changed to support ``https://`` URLs, though no one has implemented
 FTP or SMTP over SSL.
 
-The :mod:`httplib` module has been rewritten by Greg Stein to support HTTP/1.1.
-Backward compatibility with the 1.5 version of :mod:`httplib` is provided,
+The :mod:`httplib <http>` module has been rewritten by Greg Stein to support HTTP/1.1.
+Backward compatibility with the 1.5 version of :mod:`!httplib` is provided,
 though using HTTP/1.1 features such as pipelining will require rewriting code to
 use a different set of interfaces.
 
@@ -1108,7 +1108,7 @@ module.
 * :mod:`pyexpat`: An interface to the Expat XML parser. (Contributed by Paul
   Prescod.)
 
-* :mod:`robotparser`: Parse a :file:`robots.txt` file, which is used for writing
+* :mod:`robotparser <urllib.robotparser>`: Parse a :file:`robots.txt` file, which is used for writing
   web spiders that politely avoid certain areas of a web site.  The parser accepts
   the contents of a :file:`robots.txt` file, builds a set of rules from it, and
   can then answer questions about the fetchability of a given URL.  (Contributed
@@ -1129,10 +1129,10 @@ module.
   :file:`Tools/idle/BrowserControl.py`, and adapted for the standard library by
   Fred.)
 
-* :mod:`_winreg`: An interface to the Windows registry.  :mod:`_winreg` is an
+* :mod:`_winreg <winreg>`: An interface to the Windows registry.  :mod:`!_winreg` is an
   adaptation of functions that have been part of PythonWin since 1995, but has now
   been added to the core  distribution, and enhanced to support Unicode.
-  :mod:`_winreg` was written by Bill Tutt and Mark Hammond.
+  :mod:`!_winreg` was written by Bill Tutt and Mark Hammond.
 
 * :mod:`zipfile`: A module for reading and writing ZIP-format archives.  These
   are archives produced by :program:`PKZIP` on DOS/Windows or :program:`zip` on

Doc/whatsnew/2.2.rst

@@ -55,7 +55,7 @@ implemented in C.  In particular, it's not possible to subclass built-in types,
 so you can't just subclass, say, lists in order to add a single useful method to
 them. The :mod:`!UserList` module provides a class that supports all of the
 methods of lists and that can be subclassed further, but there's lots of C code
-that expects a regular Python list and won't accept a :class:`!UserList`
+that expects a regular Python list and won't accept a :class:`~collections.UserList`
 instance.
 
 Python 2.2 fixes this, and in the process adds some exciting new capabilities.
@@ -69,7 +69,7 @@ A brief summary:
 
 * It's also possible to automatically call methods on accessing or setting an
   instance attribute by using a new mechanism called :dfn:`properties`.  Many uses
-  of :meth:`!__getattr__` can be rewritten to use properties instead, making the
+  of :meth:`~object.__getattr__` can be rewritten to use properties instead, making the
   resulting code simpler and faster.  As a small side benefit, attributes can now
   have docstrings, too.
 
@@ -933,7 +933,7 @@ anyway).
 New and Improved Modules
 ========================
 
-* The :mod:`!xmlrpclib` module was contributed to the standard library by Fredrik
+* The :mod:`xmlrpclib <xmlrpc.client>` module was contributed to the standard library by Fredrik
   Lundh, providing support for writing XML-RPC clients.  XML-RPC is a simple
   remote procedure call protocol built on top of HTTP and XML. For example, the
   following snippet retrieves a list of RSS channels from the O'Reilly Network,
@@ -956,15 +956,15 @@ New and Improved Modules
      #   'description': 'A utility which converts HTML to XSL FO.',
      #   'title': 'html2fo 0.3 (Default)'}, ... ]
 
-  The :mod:`!SimpleXMLRPCServer` module makes it easy to create straightforward
+  The :mod:`SimpleXMLRPCServer <xmlrpc.server>` module makes it easy to create straightforward
   XML-RPC servers.  See http://xmlrpc.scripting.com/ for more information about XML-RPC.
 
 * The new :mod:`hmac` module implements the HMAC algorithm described by
   :rfc:`2104`. (Contributed by Gerhard Häring.)
 
 * Several functions that originally returned lengthy tuples now return
   pseudo-sequences that still behave like tuples but also have mnemonic attributes such
-  as :attr:`!memberst_mtime` or :attr:`!tm_year`. The enhanced functions include
+  as :attr:`!memberst_mtime` or :attr:`~time.struct_time.tm_year`. The enhanced functions include
   :func:`~os.stat`, :func:`~os.fstat`, :func:`~os.statvfs`, and :func:`~os.fstatvfs` in the
   :mod:`os` module, and :func:`~time.localtime`, :func:`~time.gmtime`, and :func:`~time.strptime` in
   the :mod:`time` module.

Doc/whatsnew/2.4.rst

@@ -1081,7 +1081,7 @@ complete list of changes, or look through the CVS logs for all the details.
   :func:`nsmallest` that use heaps to find the N largest or smallest values in a
   dataset without the expense of a full sort.  (Contributed by Raymond Hettinger.)
 
-* The :mod:`httplib` module now contains constants for HTTP status codes defined
+* The :mod:`httplib <http>` module now contains constants for HTTP status codes defined
   in various HTTP-related RFC documents.  Constants have names such as
   :const:`OK`, :const:`CREATED`, :const:`CONTINUE`, and
   :const:`MOVED_PERMANENTLY`; use pydoc to get a full list.  (Contributed by
@@ -1218,10 +1218,10 @@ complete list of changes, or look through the CVS logs for all the details.
   now include the string ``'%default'``, which will be replaced by the option's
   default value.  (Contributed by Greg Ward.)
 
-* The long-term plan is to deprecate the :mod:`rfc822` module in some future
+* The long-term plan is to deprecate the :mod:`!rfc822` module in some future
   Python release in favor of the :mod:`email` package. To this end, the
-  :func:`email.Utils.formatdate` function has been changed to make it usable as a
-  replacement for :func:`rfc822.formatdate`.  You may want to write new e-mail
+  :func:`email.Utils.formatdate <email.utils.formatdate>` function has been changed to make it usable as a
+  replacement for :func:`!rfc822.formatdate`.  You may want to write new e-mail
   processing code with this in mind.  (Change implemented by Anthony Baxter.)
 
 * A new ``urandom(n)`` function was added to the :mod:`os` module, returning
@@ -1308,7 +1308,7 @@ complete list of changes, or look through the CVS logs for all the details.
   sockets, and regular expression pattern objects. (Contributed by Raymond
   Hettinger.)
 
-* The :mod:`xmlrpclib` module now supports a multi-call extension for
+* The :mod:`xmlrpclib <xmlrpc.client>` module now supports a multi-call extension for
   transmitting multiple XML-RPC calls in a single HTTP operation. (Contributed by
   Brian Quinlan.)
 
@@ -1323,8 +1323,8 @@ complete list of changes, or look through the CVS logs for all the details.
 cookielib
 ---------
 
-The :mod:`cookielib` library supports client-side handling for HTTP cookies,
-mirroring the :mod:`Cookie` module's server-side cookie support. Cookies are
+The :mod:`cookielib <http.cookiejar>` library supports client-side handling for HTTP cookies,
+mirroring the :mod:`Cookie <http.cookies>` module's server-side cookie support. Cookies are
 stored in cookie jars; the library transparently stores cookies offered by the
 web server in the cookie jar, and fetches the cookie from the jar when
 connecting to the server. As in web browsers, policy objects control whether
@@ -1335,7 +1335,7 @@ are provided: one that stores cookies in the Netscape format so applications can
 use the Mozilla or Lynx cookie files, and one that stores cookies in the same
 format as the Perl libwww library.
 
-:mod:`urllib2` has been changed to interact with :mod:`cookielib`:
+:mod:`urllib2 <urllib.request>` has been changed to interact with :mod:`cookielib <http.cookiejar>`:
 :class:`HTTPCookieProcessor` manages a cookie jar that is used when accessing
 URLs.
 

Doc/whatsnew/2.5.rst

@@ -1478,8 +1478,8 @@ complete list of changes, or look through the SVN logs for all the details.
 
   .. Patch 790710
 
-* The :mod:`pickle` and :mod:`cPickle` modules no longer accept a return value
-  of ``None`` from the :meth:`__reduce__` method; the method must return a tuple
+* The :mod:`pickle` and :mod:`!cPickle` modules no longer accept a return value
+  of ``None`` from the :meth:`~object.__reduce__` method; the method must return a tuple
   of arguments instead.  The ability to return ``None`` was deprecated in Python
   2.4, so this completes the removal of the feature.
 
@@ -1519,7 +1519,7 @@ complete list of changes, or look through the SVN logs for all the details.
 
   .. Patch #1472854
 
-* The :mod:`SimpleXMLRPCServer` and :mod:`DocXMLRPCServer`  classes now have a
+* The :mod:`SimpleXMLRPCServer <xmlrpc.server>` and :mod:`DocXMLRPCServer <xmlrpc.server>`  classes now have a
   :attr:`rpc_paths` attribute that constrains XML-RPC operations to a limited set
   of URL paths; the default is to allow only ``'/'`` and ``'/RPC2'``.  Setting
   :attr:`rpc_paths` to ``None`` or an empty tuple disables  this path checking.
@@ -1650,9 +1650,9 @@ complete list of changes, or look through the SVN logs for all the details.
 
   .. Patch #754022
 
-* The :mod:`xmlrpclib` module now supports returning  :class:`~datetime.datetime` objects
-  for the XML-RPC date type.  Supply  ``use_datetime=True`` to the :func:`loads`
-  function or the :class:`Unmarshaller` class to enable this feature. (Contributed
+* The :mod:`xmlrpclib <xmlrpc.client>` module now supports returning  :class:`~datetime.datetime` objects
+  for the XML-RPC date type.  Supply  ``use_datetime=True`` to the :func:`~xmlrpc.client.loads`
+  function or the :class:`!Unmarshaller` class to enable this feature. (Contributed
   by Skip Montanaro.)
 
   .. Patch 1120353
@@ -2253,12 +2253,12 @@ code:
   appeared.  In Python 2.5, the argument must be exactly one %char specifier with
   no surrounding text.
 
-* Library: The :mod:`pickle` and :mod:`cPickle` modules no longer accept a
-  return value of ``None`` from the :meth:`__reduce__` method; the method must
+* Library: The :mod:`pickle` and :mod:`!cPickle` modules no longer accept a
+  return value of ``None`` from the :meth:`~object.__reduce__` method; the method must
   return a tuple of arguments instead.  The modules also no longer accept the
   deprecated *bin* keyword parameter.
 
-* Library: The :mod:`SimpleXMLRPCServer` and :mod:`DocXMLRPCServer`  classes now
+* Library: The :mod:`SimpleXMLRPCServer <xmlrpc.server>` and :mod:`DocXMLRPCServer <xmlrpc.server>`  classes now
   have a :attr:`rpc_paths` attribute that constrains XML-RPC operations to a
   limited set of URL paths; the default is to allow only ``'/'`` and ``'/RPC2'``.
   Setting  :attr:`rpc_paths` to ``None`` or an empty tuple disables  this path

Doc/whatsnew/2.6.rst

@@ -1082,7 +1082,7 @@ the :mod:`io` module:
 
   (In Python 2.6, :class:`io.StringIO` is implemented in
   pure Python, so it's pretty slow.   You should therefore stick with the
-  existing :mod:`StringIO` module or :mod:`cStringIO` for now.  At some
+  existing :mod:`!StringIO` module or :mod:`!cStringIO` for now.  At some
   point Python 3.0's :mod:`io` module will be rewritten into C for speed,
   and perhaps the C implementation will be  backported to the 2.x releases.)
 
@@ -1807,7 +1807,7 @@ changes, or look through the Subversion logs for all the details.
   Nubis; :issue:`1817`.)
 
   The :func:`parse_qs` and :func:`parse_qsl` functions have been
-  relocated from the :mod:`!cgi` module to the :mod:`urlparse` module.
+  relocated from the :mod:`!cgi` module to the :mod:`urlparse <urllib.parse>` module.
   The versions still available in the :mod:`!cgi` module will
   trigger :exc:`PendingDeprecationWarning` messages in 2.6
   (:issue:`600362`).
@@ -1895,8 +1895,8 @@ changes, or look through the Subversion logs for all the details.
 
   (Contributed by Raymond Hettinger.)
 
-* The :mod:`Cookie` module's :class:`Morsel` objects now support an
-  :attr:`httponly` attribute.  In some browsers. cookies with this attribute
+* The :mod:`Cookie <http.cookies>` module's :class:`~http.cookies.Morsel` objects now support an
+  :attr:`~http.cookies.Morsel.httponly` attribute.  In some browsers. cookies with this attribute
   set cannot be accessed or manipulated by JavaScript code.
   (Contributed by Arvin Schnell; :issue:`1638033`.)
 
@@ -1987,8 +1987,8 @@ changes, or look through the Subversion logs for all the details.
   (Contributed by Raymond Hettinger.)
 
 * An optional ``timeout`` parameter, specifying a timeout measured in
-  seconds, was added to the :class:`httplib.HTTPConnection` and
-  :class:`HTTPSConnection` class constructors.  (Added by Facundo
+  seconds, was added to the :class:`httplib.HTTPConnection <http.client.HTTPConnection>` and
+  :class:`HTTPSConnection <http.client.HTTPSConnection>` class constructors.  (Added by Facundo
   Batista.)
 
 * Most of the :mod:`inspect` module's functions, such as
@@ -2371,10 +2371,10 @@ changes, or look through the Subversion logs for all the details.
   ``socket(socket.AF_INET, ...)`` may be all that's required to make
   your code work with IPv6.
 
-* The base classes in the :mod:`SocketServer` module now support
-  calling a :meth:`handle_timeout` method after a span of inactivity
-  specified by the server's :attr:`timeout` attribute.  (Contributed
-  by Michael Pomraning.)  The :meth:`serve_forever` method
+* The base classes in the :mod:`SocketServer <socketserver>` module now support
+  calling a :meth:`~socketserver.BaseServer.handle_timeout` method after a span of inactivity
+  specified by the server's :attr:`~socketserver.BaseServer.timeout` attribute.  (Contributed
+  by Michael Pomraning.)  The :meth:`~socketserver.BaseServer.serve_forever` method
   now takes an optional poll interval measured in seconds,
   controlling how often the server will check for a shutdown request.
   (Contributed by Pedro Werneck and Jeffrey Yasskin;
@@ -2478,9 +2478,9 @@ changes, or look through the Subversion logs for all the details.
   ``with tempfile.NamedTemporaryFile() as tmp: ...``.
   (Contributed by Alexander Belopolsky; :issue:`2021`.)
 
-* The :mod:`test.test_support` module gained a number
+* The :mod:`test.test_support <test.support>` module gained a number
   of context managers useful for writing tests.
-  :func:`EnvironmentVarGuard` is a
+  :func:`~test.support.os_helper.EnvironmentVarGuard` is a
   context manager that temporarily changes environment variables and
   automatically restores them to their old values.
 
@@ -2577,9 +2577,9 @@ changes, or look through the Subversion logs for all the details.
   (:issue:`1513695`)
 
 * An optional ``timeout`` parameter was added to the
-  :func:`urllib.urlopen` function and the
+  :func:`urllib.urlopen <urllib.request.urlopen>` function and the
   :class:`urllib.ftpwrapper` class constructor, as well as the
-  :func:`urllib2.urlopen` function.  The parameter specifies a timeout
+  :func:`urllib2.urlopen <urllib.request.urlopen>` function.  The parameter specifies a timeout
   measured in seconds.   For example::
 
      >>> u = urllib2.urlopen("http://slow.example.com",
@@ -2604,7 +2604,7 @@ changes, or look through the Subversion logs for all the details.
   intended for testing purposes that lets you temporarily modify the
   warning filters and then restore their original values (:issue:`3781`).
 
-* The XML-RPC :class:`SimpleXMLRPCServer` and :class:`DocXMLRPCServer`
+* The XML-RPC :class:`SimpleXMLRPCServer <xmlrpc.server>` and :class:`DocXMLRPCServer <xmlrpc.server>`
   classes can now be prevented from immediately opening and binding to
   their socket by passing ``False`` as the *bind_and_activate*
   constructor parameter.  This can be used to modify the instance's
@@ -2621,11 +2621,11 @@ changes, or look through the Subversion logs for all the details.
   information.  (Contributed by Alan McIntyre as part of his
   project for Google's Summer of Code 2007.)
 
-* The :mod:`xmlrpclib` module no longer automatically converts
+* The :mod:`xmlrpclib <xmlrpc.client>` module no longer automatically converts
   :class:`datetime.date` and :class:`datetime.time` to the
-  :class:`xmlrpclib.DateTime` type; the conversion semantics were
+  :class:`xmlrpclib.DateTime <xmlrpc.client.DateTime>` type; the conversion semantics were
   not necessarily correct for all applications.  Code using
-  :mod:`xmlrpclib` should convert :class:`date` and :class:`~datetime.time`
+  :mod:`!xmlrpclib` should convert :class:`date` and :class:`~datetime.time`
   instances. (:issue:`1330538`)  The code can also handle
   dates before 1900 (contributed by Ralf Schmitt; :issue:`2014`)
   and 64-bit integers represented by using ``<i8>`` in XML-RPC responses
@@ -3274,11 +3274,11 @@ that may require changes to your code:
   :exc:`StandardError` but now it is, through :exc:`IOError`.
   (Implemented by Gregory P. Smith; :issue:`1706815`.)
 
-* The :mod:`xmlrpclib` module no longer automatically converts
+* The :mod:`xmlrpclib <xmlrpc.client>` module no longer automatically converts
   :class:`datetime.date` and :class:`datetime.time` to the
-  :class:`xmlrpclib.DateTime` type; the conversion semantics were
+  :class:`xmlrpclib.DateTime <xmlrpc.client.DateTime>` type; the conversion semantics were
   not necessarily correct for all applications.  Code using
-  :mod:`xmlrpclib` should convert :class:`date` and :class:`~datetime.time`
+  :mod:`!xmlrpclib` should convert :class:`date` and :class:`~datetime.time`
   instances. (:issue:`1330538`)
 
 * (3.0-warning mode) The :class:`Exception` class now warns