bpo-36797: Prune more legacy distutils documentation (GH-13092)

Removes more legacy distutils documentation, and more clearly
marks what is left as potentially outdated, with references to
setuptools as a replacement.

11 files changed, 37 insertions, 4 deletions

diff --git a/Doc/distutils/_setuptools_disclaimer.rst b/Doc/distutils/_setuptools_disclaimer.rst
new file mode 100644
index 0000000..cc75858
--- /dev/null
+++ b/Doc/distutils/_setuptools_disclaimer.rst
@@ -0,0 +1,5 @@
+.. note::
+
+   This document is being retained solely until the ``setuptools`` documentation
+   at https://setuptools.readthedocs.io/en/latest/setuptools.html
+   independently covers all of the relevant information currently included here.
diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst
index 1facc04..cbeedab 100644
--- a/Doc/distutils/apiref.rst
+++ b/Doc/distutils/apiref.rst
@@ -4,6 +4,16 @@
 API Reference
 *************
 
+.. seealso::
+
+   `New and changed setup.py arguments in setuptools <setuptools-setup-py>`_
+      The ``setuptools`` project adds new capabilities to the ``setup`` function
+      and other APIs, makes the API consistent across different Python versions,
+      and is hence recommended over using ``distutils`` directly.
+
+.. _setuptools-setup-py: https://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords
+
+.. include:: ./_setuptools_disclaimer.rst
 
 :mod:`distutils.core` --- Core Distutils functionality
 ======================================================
diff --git a/Doc/distutils/builtdist.rst b/Doc/distutils/builtdist.rst
index f1f3471..f44d0d0 100644
--- a/Doc/distutils/builtdist.rst
+++ b/Doc/distutils/builtdist.rst
@@ -4,6 +4,8 @@
 Creating Built Distributions
 ****************************
 
+.. include:: ./_setuptools_disclaimer.rst
+
 A "built distribution" is what you're probably used to thinking of either as a
 "binary package" or an "installer" (depending on your background).  It's not
 necessarily binary, though, because it might contain only Python source code
diff --git a/Doc/distutils/commandref.rst b/Doc/distutils/commandref.rst
index 6a2ac96..0f6fe2a 100644
--- a/Doc/distutils/commandref.rst
+++ b/Doc/distutils/commandref.rst
@@ -4,6 +4,8 @@
 Command Reference
 *****************
 
+.. include:: ./_setuptools_disclaimer.rst
+
 .. % \section{Building modules: the \protect\command{build} command family}
 .. % \label{build-cmds}
 .. % \subsubsection{\protect\command{build}}
diff --git a/Doc/distutils/configfile.rst b/Doc/distutils/configfile.rst
index 0874d05..2a5c832 100644
--- a/Doc/distutils/configfile.rst
+++ b/Doc/distutils/configfile.rst
@@ -4,6 +4,8 @@
 Writing the Setup Configuration File
 ************************************
 
+.. include:: ./_setuptools_disclaimer.rst
+
 Often, it's not possible to write down everything needed to build a distribution
 *a priori*: you may need to get some information from the user, or from the
 user's system, in order to proceed.  As long as that information is fairly
diff --git a/Doc/distutils/examples.rst b/Doc/distutils/examples.rst
index f81e06b..4ac552c 100644
--- a/Doc/distutils/examples.rst
+++ b/Doc/distutils/examples.rst
@@ -4,6 +4,8 @@
 Examples
 ********
 
+.. include:: ./_setuptools_disclaimer.rst
+
 This chapter provides a number of basic examples to help get started with
 distutils.  Additional information about using distutils can be found in the
 Distutils Cookbook.
diff --git a/Doc/distutils/extending.rst b/Doc/distutils/extending.rst
index 501fd7c..1075e81 100644
--- a/Doc/distutils/extending.rst
+++ b/Doc/distutils/extending.rst
@@ -4,6 +4,8 @@
 Extending Distutils
 *******************
 
+.. include:: ./_setuptools_disclaimer.rst
+
 Distutils can be extended in various ways.  Most extensions take the form of new
 commands or replacements for existing commands.  New commands may be written to
 support new types of platform-specific packaging, for example, while
diff --git a/Doc/distutils/index.rst b/Doc/distutils/index.rst
index d6f7640..c56fafd 100644
--- a/Doc/distutils/index.rst
+++ b/Doc/distutils/index.rst
@@ -12,10 +12,7 @@
    :ref:`distributing-index`
       The up to date module distribution documentations
 
-This document describes the Python Distribution Utilities ("Distutils") from
-the module developer's point of view, describing how to use the Distutils to
-make Python modules and extensions easily available to a wider audience with
-very little overhead for build/release/install mechanics.
+.. include:: ./_setuptools_disclaimer.rst
 
 .. note::
 
@@ -25,6 +22,11 @@ very little overhead for build/release/install mechanics.
    recommendations section <https://packaging.python.org/guides/tool-recommendations/>`__
    in the Python Packaging User Guide for more information.
 
+This document describes the Python Distribution Utilities ("Distutils") from
+the module developer's point of view, describing the underlying capabilities
+that ``setuptools`` builds on to allow Python developers to make Python modules
+and extensions readily available to a wider audience.
+
 .. toctree::
    :maxdepth: 2
    :numbered:
diff --git a/Doc/distutils/introduction.rst b/Doc/distutils/introduction.rst
index 7721484..1f8a560 100644
--- a/Doc/distutils/introduction.rst
+++ b/Doc/distutils/introduction.rst
@@ -4,6 +4,8 @@
 An Introduction to Distutils
 ****************************
 
+.. include:: ./_setuptools_disclaimer.rst
+
 This document covers using the Distutils to distribute your Python modules,
 concentrating on the role of developer/distributor: if you're looking for
 information on installing Python modules, you should refer to the
diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst
index 1f99f62..4386a60 100644
--- a/Doc/distutils/setupscript.rst
+++ b/Doc/distutils/setupscript.rst
@@ -4,6 +4,8 @@
 Writing the Setup Script
 ************************
 
+.. include:: ./_setuptools_disclaimer.rst
+
 The setup script is the centre of all activity in building, distributing, and
 installing modules using the Distutils.  The main purpose of the setup script is
 to describe your module distribution to the Distutils, so that the various
diff --git a/Doc/distutils/sourcedist.rst b/Doc/distutils/sourcedist.rst
index 0ac8ef4..0600663 100644
--- a/Doc/distutils/sourcedist.rst
+++ b/Doc/distutils/sourcedist.rst
@@ -4,6 +4,8 @@
 Creating a Source Distribution
 ******************************
 
+.. include:: ./_setuptools_disclaimer.rst
+
 As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command
 to create a source distribution.  In the simplest case, ::