Issue #22711: improve links in new distribution docs

- key term hyperlinks for distutils, setuptools & wheel
- distutils landing page links directly to setuptools docs
- short summary of setuptools benefits provided with link

2 files changed, 29 insertions, 11 deletions

diff --git a/Doc/distributing/index.rst b/Doc/distributing/index.rst
index 9146b81..04606f1 100644
--- a/Doc/distributing/index.rst
+++ b/Doc/distributing/index.rst
@@ -41,26 +41,28 @@ Key terms
   file format standards. They maintain a variety of tools, documentation
   and issue trackers on both `GitHub <https://github.com/pypa>`__ and
   `BitBucket <https://bitbucket.org/pypa/>`__.
-* ``distutils`` is the original build and distribution system first added to
-  the Python standard library in 1998. While direct use of ``distutils`` is
-  being phased out, it still laid the foundation for the current packaging
+* :mod:`distutils` is the original build and distribution system first added
+  to the Python standard library in 1998. While direct use of :mod:`distutils`
+  is being phased out, it still laid the foundation for the current packaging
   and distribution infrastructure, and it not only remains part of the
   standard library, but its name lives on in other ways (such as the name
   of the mailing list used to coordinate Python packaging standards
   development).
-* ``setuptools`` is a (largely) drop-in replacement for ``distutils`` first
+* `setuptools`_ is a (largely) drop-in replacement for :mod:`distutils` first
   published in 2004. Its most notable addition over the unmodified
-  ``distutils`` tools was the ability to declare dependencies on other
+  :mod:`distutils` tools was the ability to declare dependencies on other
   packages. It is currently recommended as a more regularly updated
-  alternative to ``distutils`` that offers consistent support for more
+  alternative to :mod:`distutils` that offers consistent support for more
   recent packaging standards across a wide range of Python versions.
-* ``wheel`` (in this context) is a project that adds the ``bdist_wheel``
-  command to ``distutils``/``setuptools``. This produces a cross platform
+* `wheel`_ (in this context) is a project that adds the ``bdist_wheel``
+  command to :mod:`distutils`/`setuptools`_. This produces a cross platform
   binary packaging format (called "wheels" or "wheel files" and defined in
   :pep:`427`) that allows Python libraries, even those including binary
   extensions, to be installed on a system without needing to be built
   locally.
 
+.. _setuptools: https://setuptools.pypa.io/en/latest/setuptools.html
+.. _wheel: http://wheel.readthedocs.org
 
 Open source licensing and collaboration
 =======================================
diff --git a/Doc/library/distutils.rst b/Doc/library/distutils.rst
index 8e3732b..a7ad837 100644
--- a/Doc/library/distutils.rst
+++ b/Doc/library/distutils.rst
@@ -13,9 +13,25 @@ additional modules into a Python installation.  The new modules may be either
 collections of Python packages which include modules coded in both Python and C.
 
 Most Python users will *not* want to use this module directly, but instead
-use the cross-version tools maintained by the Python Packaging Authority.
-Refer to the `Python Packaging User Guide <http://packaging.python.org>`_
-for more information.
+use the cross-version tools maintained by the Python Packaging Authority. In
+particular,
+`setuptools <https://setuptools.pypa.io/en/latest/setuptools.html>`__ 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
+
+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 <http://packaging.python.org>`_ for more
+information.
 
 For the benefits of packaging tool authors and users seeking a deeper
 understanding of the details of the current packaging and distribution