[3.9] bpo-47061: document module deprecations due to PEP 594 (GH-31984) (GH-32082)

Also removed asynchat, asyncore, and smtpd from their respective toctree entries so they are only  in the superceded subtree.
(cherry picked from commit 9ac2de922a0f783bd43b8e026e4fb70fd1888572)

Co-authored-by: Brett Cannon <brett@python.org>

Automerge-Triggered-By: GH:brettcannon

26 files changed, 92 insertions, 22 deletions

diff --git a/Doc/library/aifc.rst b/Doc/library/aifc.rst
index 2e917cf..edb4bf8 100644
--- a/Doc/library/aifc.rst
+++ b/Doc/library/aifc.rst
@@ -3,6 +3,7 @@
 
 .. module:: aifc
    :synopsis: Read and write audio files in AIFF or AIFC format.
+   :deprecated:
 
 **Source code:** :source:`Lib/aifc.py`
 
@@ -11,6 +12,10 @@
    single: AIFF
    single: AIFF-C
 
+
+.. deprecated:: 3.11
+   The :mod:`aifc` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 This module provides support for reading and writing AIFF and AIFF-C files.
diff --git a/Doc/library/audioop.rst b/Doc/library/audioop.rst
index bad9da2..eae2060 100644
--- a/Doc/library/audioop.rst
+++ b/Doc/library/audioop.rst
@@ -3,6 +3,10 @@
 
 .. module:: audioop
    :synopsis: Manipulate raw audio data.
+   :deprecated:
+
+.. deprecated:: 3.11
+   The :mod:`audioop` module is deprecated (see :pep:`594` for details).
 
 --------------
 
diff --git a/Doc/library/cgi.rst b/Doc/library/cgi.rst
index 3ec919e..80c4d80 100644
--- a/Doc/library/cgi.rst
+++ b/Doc/library/cgi.rst
@@ -3,6 +3,7 @@
 
 .. module:: cgi
    :synopsis: Helpers for running Python scripts via the Common Gateway Interface.
+   :deprecated:
 
 **Source code:** :source:`Lib/cgi.py`
 
@@ -14,6 +15,9 @@
    single: URL
    single: Common Gateway Interface
 
+.. deprecated:: 3.11
+   The :mod:`cgi` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 Support module for Common Gateway Interface (CGI) scripts.
diff --git a/Doc/library/cgitb.rst b/Doc/library/cgitb.rst
index 5f3a647..3494146 100644
--- a/Doc/library/cgitb.rst
+++ b/Doc/library/cgitb.rst
@@ -3,6 +3,7 @@
 
 .. module:: cgitb
    :synopsis: Configurable traceback handler for CGI scripts.
+   :deprecated:
 
 .. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
@@ -15,6 +16,9 @@
    single: exceptions; in CGI scripts
    single: tracebacks; in CGI scripts
 
+.. deprecated:: 3.11
+   The :mod:`cgitb` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`cgitb` module provides a special exception handler for Python scripts.
diff --git a/Doc/library/chunk.rst b/Doc/library/chunk.rst
index 5e24df9..7999420 100644
--- a/Doc/library/chunk.rst
+++ b/Doc/library/chunk.rst
@@ -3,6 +3,7 @@
 
 .. module:: chunk
    :synopsis: Module to read IFF chunks.
+   :deprecated:
 
 .. moduleauthor:: Sjoerd Mullender <sjoerd@acm.org>
 .. sectionauthor:: Sjoerd Mullender <sjoerd@acm.org>
@@ -16,6 +17,9 @@
    single: Real Media File Format
    single: RMFF
 
+.. deprecated:: 3.11
+   The :mod:`chunk` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 This module provides an interface for reading files that use EA IFF 85 chunks.
diff --git a/Doc/library/crypt.rst b/Doc/library/crypt.rst
index d25c626..73df87c 100644
--- a/Doc/library/crypt.rst
+++ b/Doc/library/crypt.rst
@@ -4,6 +4,7 @@
 .. module:: crypt
    :platform: Unix
    :synopsis: The crypt() function used to check Unix passwords.
+   :deprecated:
 
 .. moduleauthor:: Steven D. Majewski <sdm7g@virginia.edu>
 .. sectionauthor:: Steven D. Majewski <sdm7g@virginia.edu>
@@ -15,6 +16,9 @@
    single: crypt(3)
    pair: cipher; DES
 
+.. deprecated:: 3.11
+   The :mod:`crypt` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 This module implements an interface to the :manpage:`crypt(3)` routine, which is
diff --git a/Doc/library/fileformats.rst b/Doc/library/fileformats.rst
index e9c2e1f..7b33b33 100644
--- a/Doc/library/fileformats.rst
+++ b/Doc/library/fileformats.rst
@@ -13,5 +13,4 @@ that aren't markup languages and are not related to e-mail.
    csv.rst
    configparser.rst
    netrc.rst
-   xdrlib.rst
    plistlib.rst
diff --git a/Doc/library/imghdr.rst b/Doc/library/imghdr.rst
index 800e919..f63a0fa 100644
--- a/Doc/library/imghdr.rst
+++ b/Doc/library/imghdr.rst
@@ -3,9 +3,13 @@
 
 .. module:: imghdr
    :synopsis: Determine the type of image contained in a file or byte stream.
+   :deprecated:
 
 **Source code:** :source:`Lib/imghdr.py`
 
+.. deprecated:: 3.11
+   The :mod:`imghdr` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`imghdr` module determines the type of image contained in a file or
diff --git a/Doc/library/internet.rst b/Doc/library/internet.rst
index b8950bb..c8bab2a 100644
--- a/Doc/library/internet.rst
+++ b/Doc/library/internet.rst
@@ -20,8 +20,6 @@ is currently supported on most popular platforms.  Here is an overview:
 .. toctree::
 
    webbrowser.rst
-   cgi.rst
-   cgitb.rst
    wsgiref.rst
    urllib.rst
    urllib.request.rst
@@ -33,10 +31,7 @@ is currently supported on most popular platforms.  Here is an overview:
    ftplib.rst
    poplib.rst
    imaplib.rst
-   nntplib.rst
    smtplib.rst
-   smtpd.rst
-   telnetlib.rst
    uuid.rst
    socketserver.rst
    http.server.rst
diff --git a/Doc/library/ipc.rst b/Doc/library/ipc.rst
index b88a174..4849c82 100644
--- a/Doc/library/ipc.rst
+++ b/Doc/library/ipc.rst
@@ -22,7 +22,5 @@ The list of modules described in this chapter is:
    ssl.rst
    select.rst
    selectors.rst
-   asyncore.rst
-   asynchat.rst
    signal.rst
    mmap.rst
diff --git a/Doc/library/mm.rst b/Doc/library/mm.rst
index c8f79c4..cd06e93 100644
--- a/Doc/library/mm.rst
+++ b/Doc/library/mm.rst
@@ -11,12 +11,5 @@ discretion of the installation.  Here's an overview:
 
 .. toctree::
 
-   audioop.rst
-   aifc.rst
-   sunau.rst
    wave.rst
-   chunk.rst
    colorsys.rst
-   imghdr.rst
-   sndhdr.rst
-   ossaudiodev.rst
diff --git a/Doc/library/msilib.rst b/Doc/library/msilib.rst
index 83b3d49..5ce18a1 100644
--- a/Doc/library/msilib.rst
+++ b/Doc/library/msilib.rst
@@ -4,6 +4,7 @@
 .. module:: msilib
    :platform: Windows
    :synopsis: Creation of Microsoft Installer files, and CAB files.
+   :deprecated:
 
 .. moduleauthor:: Martin v. Löwis <martin@v.loewis.de>
 .. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
@@ -12,6 +13,9 @@
 
 .. index:: single: msi
 
+.. deprecated:: 3.11
+   The :mod:`msilib` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`msilib` supports the creation of Microsoft Installer (``.msi``) files.
diff --git a/Doc/library/netdata.rst b/Doc/library/netdata.rst
index 4915016..8a3ad68 100644
--- a/Doc/library/netdata.rst
+++ b/Doc/library/netdata.rst
@@ -20,4 +20,3 @@ on the Internet.
    binhex.rst
    binascii.rst
    quopri.rst
-   uu.rst
diff --git a/Doc/library/nis.rst b/Doc/library/nis.rst
index 10c67cb..f6b6ea8 100644
--- a/Doc/library/nis.rst
+++ b/Doc/library/nis.rst
@@ -5,10 +5,14 @@
 .. module:: nis
    :platform: Unix
    :synopsis: Interface to Sun's NIS (Yellow Pages) library.
+   :deprecated:
 
 .. moduleauthor:: Fred Gansevles <Fred.Gansevles@cs.utwente.nl>
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
+.. deprecated:: 3.11
+   The :mod:`nis` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`nis` module gives a thin wrapper around the NIS library, useful for
diff --git a/Doc/library/nntplib.rst b/Doc/library/nntplib.rst
index e7ec904..2a996e4 100644
--- a/Doc/library/nntplib.rst
+++ b/Doc/library/nntplib.rst
@@ -3,6 +3,7 @@
 
 .. module:: nntplib
    :synopsis: NNTP protocol client (requires sockets).
+   :deprecated:
 
 **Source code:** :source:`Lib/nntplib.py`
 
@@ -10,6 +11,9 @@
    pair: NNTP; protocol
    single: Network News Transfer Protocol
 
+.. deprecated:: 3.11
+   The :mod:`nntplib` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 This module defines the class :class:`NNTP` which implements the client side of
diff --git a/Doc/library/ossaudiodev.rst b/Doc/library/ossaudiodev.rst
index a7d3dac..e0f0a6b 100644
--- a/Doc/library/ossaudiodev.rst
+++ b/Doc/library/ossaudiodev.rst
@@ -4,6 +4,10 @@
 .. module:: ossaudiodev
    :platform: Linux, FreeBSD
    :synopsis: Access to OSS-compatible audio devices.
+   :deprecated:
+
+.. deprecated:: 3.11
+   The :mod:`ossaudiodev` module is deprecated (see :pep:`594` for details).
 
 --------------
 
diff --git a/Doc/library/pipes.rst b/Doc/library/pipes.rst
index 0a22da1..25f8085 100644
--- a/Doc/library/pipes.rst
+++ b/Doc/library/pipes.rst
@@ -4,11 +4,15 @@
 .. module:: pipes
    :platform: Unix
    :synopsis: A Python interface to Unix shell pipelines.
+   :deprecated:
 
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
 **Source code:** :source:`Lib/pipes.py`
 
+.. deprecated:: 3.11
+   The :mod:`pipes` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`pipes` module defines a class to abstract the concept of a *pipeline*
diff --git a/Doc/library/sndhdr.rst b/Doc/library/sndhdr.rst
index 6bfa9a9..41bce18 100644
--- a/Doc/library/sndhdr.rst
+++ b/Doc/library/sndhdr.rst
@@ -3,6 +3,7 @@
 
 .. module:: sndhdr
    :synopsis: Determine type of a sound file.
+   :deprecated:
 
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 .. Based on comments in the module source file.
@@ -13,6 +14,9 @@
    single: A-LAW
    single: u-LAW
 
+.. deprecated:: 3.11
+   The :mod:`sndhdr` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`sndhdr` provides utility functions which attempt to determine the type
diff --git a/Doc/library/spwd.rst b/Doc/library/spwd.rst
index c6cad2a..cb31a10 100644
--- a/Doc/library/spwd.rst
+++ b/Doc/library/spwd.rst
@@ -4,6 +4,10 @@
 .. module:: spwd
    :platform: Unix
    :synopsis: The shadow password database (getspnam() and friends).
+   :deprecated:
+
+.. deprecated:: 3.11
+   The :mod:`spwd` module is deprecated (see :pep:`594` for details).
 
 --------------
 
diff --git a/Doc/library/sunau.rst b/Doc/library/sunau.rst
index aad6f93..cfb1257 100644
--- a/Doc/library/sunau.rst
+++ b/Doc/library/sunau.rst
@@ -3,11 +3,15 @@
 
 .. module:: sunau
    :synopsis: Provide an interface to the Sun AU sound format.
+   :deprecated:
 
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
 **Source code:** :source:`Lib/sunau.py`
 
+.. deprecated:: 3.11
+   The :mod:`sunau` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`sunau` module provides a convenient interface to the Sun AU sound
diff --git a/Doc/library/superseded.rst b/Doc/library/superseded.rst
index fd23e4d..e3f9b0d 100644
--- a/Doc/library/superseded.rst
+++ b/Doc/library/superseded.rst
@@ -10,8 +10,26 @@ backwards compatibility. They have been superseded by other modules.
 
 .. toctree::
 
+   aifc.rst
    asynchat.rst
    asyncore.rst
-   smtpd.rst
+   audioop.rst
+   cgi.rst
+   cgitb.rst
+   chunk.rst
+   crypt.rst
+   imghdr.rst
    imp.rst
+   msilib.rst
+   nntplib.rst
+   nis.rst
    optparse.rst
+   ossaudiodev.rst
+   pipes.rst
+   smtpd.rst
+   sndhdr.rst
+   spwd.rst
+   sunau.rst
+   telnetlib.rst
+   uu.rst
+   xdrlib.rst
diff --git a/Doc/library/telnetlib.rst b/Doc/library/telnetlib.rst
index 48a9aea..97b0a71 100644
--- a/Doc/library/telnetlib.rst
+++ b/Doc/library/telnetlib.rst
@@ -3,6 +3,7 @@
 
 .. module:: telnetlib
    :synopsis: Telnet client class.
+   :deprecated:
 
 .. sectionauthor:: Skip Montanaro <skip@pobox.com>
 
@@ -10,6 +11,9 @@
 
 .. index:: single: protocol; Telnet
 
+.. deprecated:: 3.11
+   The :mod:`telnetlib` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`telnetlib` module provides a :class:`Telnet` class that implements the
diff --git a/Doc/library/unix.rst b/Doc/library/unix.rst
index 04d4081..4553a10 100644
--- a/Doc/library/unix.rst
+++ b/Doc/library/unix.rst
@@ -13,14 +13,10 @@ of it.  Here's an overview:
 
    posix.rst
    pwd.rst
-   spwd.rst
    grp.rst
-   crypt.rst
    termios.rst
    tty.rst
    pty.rst
    fcntl.rst
-   pipes.rst
    resource.rst
-   nis.rst
    syslog.rst
diff --git a/Doc/library/uu.rst b/Doc/library/uu.rst
index 0bc8021..c341bc8 100644
--- a/Doc/library/uu.rst
+++ b/Doc/library/uu.rst
@@ -3,11 +3,15 @@
 
 .. module:: uu
    :synopsis: Encode and decode files in uuencode format.
+   :deprecated:
 
 .. moduleauthor:: Lance Ellinghouse
 
 **Source code:** :source:`Lib/uu.py`
 
+.. deprecated:: 3.11
+   The :mod:`uu` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 This module encodes and decodes files in uuencode format, allowing arbitrary
diff --git a/Doc/library/windows.rst b/Doc/library/windows.rst
index b60d4e4..4d72ead 100644
--- a/Doc/library/windows.rst
+++ b/Doc/library/windows.rst
@@ -9,7 +9,6 @@ This chapter describes modules that are only available on MS Windows platforms.
 
 .. toctree::
 
-   msilib.rst
    msvcrt.rst
    winreg.rst
    winsound.rst
diff --git a/Doc/library/xdrlib.rst b/Doc/library/xdrlib.rst
index 42a03a4..060b2e2 100644
--- a/Doc/library/xdrlib.rst
+++ b/Doc/library/xdrlib.rst
@@ -3,6 +3,7 @@
 
 .. module:: xdrlib
    :synopsis: Encoders and decoders for the External Data Representation (XDR).
+   :deprecated:
 
 **Source code:** :source:`Lib/xdrlib.py`
 
@@ -10,6 +11,9 @@
    single: XDR
    single: External Data Representation
 
+.. deprecated:: 3.11
+   The :mod:`xdrlib` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`xdrlib` module supports the External Data Representation Standard as