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)

5 files changed, 51 insertions, 29 deletions

diff --git a/Doc/distributing/index.rst b/Doc/distributing/index.rst
index d51ff99..82ecd2c 100644
--- a/Doc/distributing/index.rst
+++ b/Doc/distributing/index.rst
@@ -61,7 +61,7 @@ Key terms
   extensions, to be installed on a system without needing to be built
   locally.
 
-.. _setuptools: https://setuptools.pypa.io/en/latest/setuptools.html
+.. _setuptools: https://setuptools.readthedocs.io/en/latest/
 .. _wheel: https://wheel.readthedocs.org
 
 Open source licensing and collaboration
diff --git a/Doc/distutils/index.rst b/Doc/distutils/index.rst
index 1f21e14..a697f50 100644
--- a/Doc/distutils/index.rst
+++ b/Doc/distutils/index.rst
@@ -1,12 +1,17 @@
 .. _distutils-index:
 
-###############################
-  Distributing Python Modules
-###############################
+##############################################
+  Distributing Python Modules (Legacy version)
+##############################################
 
 :Authors: Greg Ward, Anthony Baxter
 :Email: distutils-sig@python.org
 
+.. seealso::
+
+   :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
diff --git a/Doc/install/index.rst b/Doc/install/index.rst
index 893db1e..029aff5 100644
--- a/Doc/install/index.rst
+++ b/Doc/install/index.rst
@@ -2,14 +2,19 @@
 
 .. _install-index:
 
-*****************************
-  Installing Python Modules
-*****************************
+********************************************
+  Installing Python Modules (Legacy version)
+********************************************
 
 :Author: Greg Ward
 
 .. TODO: Fill in XXX comments
 
+.. 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.
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 @@ additional modules into a Python installation.  The new modules may be either
 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:
-
-
-.. seealso::
-
-   :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.
-
-   :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.
-
+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
+
+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.
+
+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`
+* :ref:`distutils-index`
diff --git a/Doc/tools/templates/indexcontent.html b/Doc/tools/templates/indexcontent.html
index 3da2605..6488c16 100644
--- a/Doc/tools/templates/indexcontent.html
+++ b/Doc/tools/templates/indexcontent.html
@@ -16,14 +16,14 @@
       <p class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">{% trans %}Python HOWTOs{% endtrans %}</a><br/>
          <span class="linkdescr">{% trans %}in-depth documents on specific topics{% endtrans %}</span></p>
     </td><td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("installing/index") }}">{% trans %}Installing Python Modules{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}installing from the Python Package Index &amp; other sources{% endtrans %}</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("distributing/index") }}">{% trans %}Distributing Python Modules{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}publishing modules for installation by others{% endtrans %}</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("extending/index") }}">{% trans %}Extending and Embedding{% endtrans %}</a><br/>
          <span class="linkdescr">{% trans %}tutorial for C/C++ programmers{% endtrans %}</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("c-api/index") }}">{% trans %}Python/C API{% endtrans %}</a><br/>
          <span class="linkdescr">{% trans %}reference for C/C++ programmers{% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("install/index") }}">{% trans %}Installing Python Modules{% endtrans %}</a><br/>
-         <span class="linkdescr">{% trans %}information for installers &amp; sys-admins{% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("distutils/index") }}">{% trans %}Distributing Python Modules{% endtrans %}</a><br/>
-         <span class="linkdescr">{% trans %}sharing modules with others{% endtrans %}</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">{% trans %}FAQs{% endtrans %}</a><br/>
          <span class="linkdescr">{% trans %}frequently asked questions (with answers!){% endtrans %}</span></p>
     </td></tr>