[Python-checkins] bpo-36797: Prune more legacy distutils documentation (GH-13092)
Nick Coghlan
webhook-mailer at python.org
Tue May 14 08:04:44 EDT 2019
https://github.com/python/cpython/commit/dae1229729920e3aa2be015453b7f702dff9b375
commit: dae1229729920e3aa2be015453b7f702dff9b375
branch: master
author: Nick Coghlan <ncoghlan at gmail.com>
committer: GitHub <noreply at github.com>
date: 2019-05-14T22:04:30+10:00
summary:
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.
files:
A Doc/distutils/_setuptools_disclaimer.rst
A Misc/NEWS.d/next/Documentation/2019-05-05-07-58-50.bpo-36797.W1X4On.rst
M Doc/distutils/apiref.rst
M Doc/distutils/builtdist.rst
M Doc/distutils/commandref.rst
M Doc/distutils/configfile.rst
M Doc/distutils/examples.rst
M Doc/distutils/extending.rst
M Doc/distutils/index.rst
M Doc/distutils/introduction.rst
M Doc/distutils/setupscript.rst
M Doc/distutils/sourcedist.rst
M Doc/install/index.rst
M Doc/tools/susp-ignored.csv
diff --git a/Doc/distutils/_setuptools_disclaimer.rst b/Doc/distutils/_setuptools_disclaimer.rst
new file mode 100644
index 000000000000..cc75858326d4
--- /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 1facc0408d5b..cbeedab5bb12 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 f1f347126160..f44d0d039f45 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 6a2ac960f1e1..0f6fe2aba865 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 0874d05fe703..2a5c8329e318 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 f81e06b5e605..4ac552c7c699 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 501fd7c564c6..1075e81779a7 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 d6f7640fcb68..c56fafd68d8f 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 7721484fe737..1f8a560e1386 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 1f99f62f6aff..4386a60b664b 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 0ac8ef41ddc2..0600663d00e9 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, ::
diff --git a/Doc/install/index.rst b/Doc/install/index.rst
index f6a8cd6833a9..e14232415be6 100644
--- 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 3672955bf55b..31b22665eca4 100644
--- 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
index 000000000000..5ca55556c887
--- /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.
More information about the Python-checkins
mailing list