Issue #26014: Guide 2.7 users to the new packaging documentation:
- the top-level 2.7 docs page now links to the newer doc pages
(installing and distribution) rather than the legacy ones
- the legacy install and distutils pages are now labeled as "legacy"
- the library/distutils page is updated to match the 3.x version
- "See also" links to the new docs are now provided in the legacy pages
- links to setuptools documentation have been updated
(original patch by Susan Sun)
diff --git a/Doc/library/distutils.rst b/Doc/library/distutils.rst
index 534faab..12ad8c0 100644
--- a/Doc/library/distutils.rst
+++ b/Doc/library/distutils.rst
@@ -1,10 +1,9 @@
-
:mod:`distutils` --- Building and installing Python modules
===========================================================
.. module:: distutils
- :synopsis: Support for building and installing Python modules into an existing Python
- installation.
+ :synopsis: Support for building and installing Python modules into an
+ existing Python installation.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
@@ -13,18 +12,31 @@
100%-pure Python, or may be extension modules written in C, or may be
collections of Python packages which include modules coded in both Python and C.
-This package is discussed in two separate chapters:
+Most Python users will *not* want to use this module directly, but instead
+use the cross-version tools maintained by the Python Packaging Authority. In
+particular,
+`setuptools <https://setuptools.readthedocs.io/en/latest/>`__ is an
+enhanced alternative to :mod:`distutils` that provides:
+* support for declaring project dependencies
+* additional mechanisms for configuring which files to include in source
+ releases (including plugins for integration with version control systems)
+* the ability to declare project "entry points", which can be used as the
+ basis for application plugin systems
+* the ability to automatically generate Windows command line executables at
+ installation time rather than needing to prebuild them
+* consistent behaviour across all supported Python versions
-.. seealso::
+The recommended `pip <https://pip.pypa.io/>`__ installer runs all
+``setup.py`` scripts with ``setuptools``, even if the script itself only
+imports ``distutils``. Refer to the
+`Python Packaging User Guide <https://packaging.python.org>`_ for more
+information.
- :ref:`distutils-index`
- The manual for developers and packagers of Python modules. This describes how
- to prepare :mod:`distutils`\ -based packages so that they may be easily
- installed into an existing Python installation.
+For the benefits of packaging tool authors and users seeking a deeper
+understanding of the details of the current packaging and distribution
+system, the legacy :mod:`distutils` based user documentation and API
+reference remain available:
- :ref:`install-index`
- An "administrators" manual which includes information on installing modules into
- an existing Python installation. You do not need to be a Python programmer to
- read this manual.
-
+* :ref:`install-index`
+* :ref:`distutils-index`