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.

diff --git a/Doc/distutils/_setuptools_disclaimer.rst b/Doc/distutils/_setuptools_disclaimer.rst
new file mode 100644 (file)
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 1facc0408d5b0f6a4732e508404bde5f9648296b..cbeedab5bb1225ae820615061ba8990a2743159b 100644 (file)
--- 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 f1f3471261600ea38b04cb38e47f757d7359aa3d..f44d0d039f45f4036a7f10e8dbbd1d73b622a129 100644 (file)
--- 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 6a2ac960f1e1efb12a83df823d72a9aa95356dc5..0f6fe2aba865f819edf8914ba0148a93ee7398fc 100644 (file)
--- 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 0874d05fe703a17a5cc9ac5b95162e470a8e6069..2a5c8329e318b7d244594ab626db24f2124c9ac2 100644 (file)
--- 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 f81e06b5e60578a75a909a4182e24a32dbe47ac1..4ac552c7c6997af45a84059b78968348b339d815 100644 (file)
--- 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 501fd7c564c6b98ffe61dffa11c49d70459bda1c..1075e81779a7bae6806949bcd5cc089df856d3d0 100644 (file)
--- 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 d6f7640fcb6826a712cc19cc87b276f8edc1c156..c56fafd68d8fdcbdcd2cab02680052eac6c21389 100644 (file)
--- 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 7721484fe737178988767223f315c8321900c8a7..1f8a560e138616fed5289044b6c9864dc8c892e6 100644 (file)
--- 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 1f99f62f6affefb5d7960929ef3ee3895da9ddbc..4386a60b664bfb3581a8d554cdbf6278164a34dc 100644 (file)
--- 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 0ac8ef41ddc20fd710466cf6ff93cc166be488be..0600663d00e9dc28b523bd6c8e1855d0a9d61206 100644 (file)
--- 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, ::
 

diff --git a/Doc/install/index.rst b/Doc/install/index.rst
index f6a8cd6833a9ad18908b6cdca1b17de7d3440563..e14232415be6f79375b6a243a509d8e8baa671f7 100644 (file)
--- a/Doc/install/index.rst
+++ b/Doc/install/index.rst
@@ -13,23 +13,10 @@
 .. seealso::
 
    :ref:`installing-index`
-      The up to date module installation documentations
-
-.. The audience for this document includes people who don't know anything
-   about Python and aren't about to learn the language just in order to
-   install and maintain it for their users, i.e. system administrators.
-   Thus, I have to be sure to explain the basics at some point:
-   sys.path and PYTHONPATH at least.  Should probably give pointers to
-   other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc.
-
-   Finally, it might be useful to include all the material from my "Care
-   and Feeding of a Python Installation" talk in here somewhere.  Yow!
-
-This document describes the Python Distribution Utilities ("Distutils") from the
-end-user's point-of-view, describing how to extend the capabilities of a
-standard Python installation by building and installing third-party Python
-modules and extensions.
+      The up to date module installation documentation. For regular Python
+      usage, you almost certainly want that document rather than this one.
 
+.. include:: ../distutils/_setuptools_disclaimer.rst
 
 .. note::
 
@@ -46,59 +33,26 @@ modules and extensions.
 Introduction
 ============
 
-Although Python's extensive standard library covers many programming needs,
-there often comes a time when you need to add some new functionality to your
-Python installation in the form of third-party modules.  This might be necessary
-to support your own programming, or to support an application that you want to
-use and that happens to be written in Python.
-
-In the past, there has been little support for adding third-party modules to an
-existing Python installation.  With the introduction of the Python Distribution
-Utilities (Distutils for short) in Python 2.0, this changed.
-
-This document is aimed primarily at the people who need to install third-party
-Python modules: end-users and system administrators who just need to get some
-Python application running, and existing Python programmers who want to add some
-new goodies to their toolbox.  You don't need to know Python to read this
-document; there will be some brief forays into using Python's interactive mode
-to explore your installation, but that's it.  If you're looking for information
-on how to distribute your own Python modules so that others may use them, see
-the :ref:`distutils-index` manual.  :ref:`debug-setup-script` may also be of
-interest.
-
-
-.. _inst-trivial-install:
-
-Best case: trivial installation
--------------------------------
-
-In the best case, someone will have prepared a special version of the module
-distribution you want to install that is targeted specifically at your platform
-and is installed just like any other software on your platform.  For example,
-the module developer might make an executable installer available for Windows
-users, an RPM package for users of RPM-based Linux systems (Red Hat, SuSE,
-Mandrake, and many others), a Debian package for users of Debian-based Linux
-systems, and so forth.
-
-In that case, you would download the installer appropriate to your platform and
-do the obvious thing with it: run it if it's an executable installer, ``rpm
---install`` it if it's an RPM, etc.  You don't need to run Python or a setup
-script, you don't need to compile anything---you might not even need to read any
-instructions (although it's always a good idea to do so anyway).
-
-Of course, things will not always be that easy.  You might be interested in a
-module distribution that doesn't have an easy-to-use installer for your
-platform.  In that case, you'll have to start with the source distribution
-released by the module's author/maintainer.  Installing from a source
-distribution is not too hard, as long as the modules are packaged in the
-standard way.  The bulk of this document is about building and installing
-modules from standard source distributions.
+In Python 2.0, the ``distutils`` API was first added to the standard library.
+This provided Linux distro maintainers with a standard way of converting
+Python projects into Linux distro packages, and system administrators with a
+standard way of installing them directly onto target systems.
+
+In the many years since Python 2.0 was released, tightly coupling the build
+system and package installer to the language runtime release cycle has turned
+out to be problematic, and it is now recommended that projects use the
+``pip`` package installer and the ``setuptools`` build system, rather than
+using ``distutils`` directly.
+
+See :ref:`installing-index` and :ref:`distributing-index` for more details.
 
+This legacy documentation is being retained only until we're confident that the
+``setuptools`` documentation covers everything needed.
 
 .. _inst-new-standard:
 
-The new standard: Distutils
----------------------------
+Distutils based source distributions
+------------------------------------
 
 If you download a module source distribution, you can tell pretty quickly if it
 was packaged and distributed in the standard way, i.e. using the Distutils.

diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv
index 3672955bf55b1108c3ee7e88d0c0bebbcd1c5247..31b22665eca475f421d5f50904690f5a54503b72 100644 (file)
--- a/Doc/tools/susp-ignored.csv
+++ b/Doc/tools/susp-ignored.csv
@@ -4,7 +4,7 @@ c-api/sequence,,:i2,del o[i1:i2]
 c-api/sequence,,:i2,o[i1:i2]
 c-api/unicode,,:end,str[start:end]
 c-api/unicode,,:start,unicode[start:start+length]
-distutils/examples,267,`,This is the description of the ``foobar`` package.
+distutils/examples,274,`,This is the description of the ``foobar`` package.
 distutils/setupscript,,::,
 extending/embedding,,:numargs,"if(!PyArg_ParseTuple(args, "":numargs""))"
 extending/extending,,:myfunction,"PyArg_ParseTuple(args, ""D:myfunction"", &c);"

diff --git a/Misc/NEWS.d/next/Documentation/2019-05-05-07-58-50.bpo-36797.W1X4On.rst b/Misc/NEWS.d/next/Documentation/2019-05-05-07-58-50.bpo-36797.W1X4On.rst
new file mode 100644 (file)
index 0000000..5ca5555
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2019-05-05-07-58-50.bpo-36797.W1X4On.rst
@@ -0,0 +1,3 @@
+More of the legacy distutils documentation has been either pruned, or else
+more clearly marked as being retained solely until the setuptools
+documentation covers it independently.