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

ncoghlan · web-flow · commit dae122972992 · 2019-05-14T22:04:30.000+10:00
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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
