Improve docs by avoiding confusion with distutils

The existing docs seem to assume that the user is familiar with the
history of packaging in the Python ecosystem (or at least know what is
`distutils`).

Since that is not always the case and that `distutils` is in the process
of being adopted by `setuptools`, the documentation should be changed
to minimize mentions to `distutils` and avoid expecting too much
knowledge from the users.

The benefit of this approach is that it can make the docs more
accessible and easier to understand.

Changes:

- Modify landing page to clarify what `setuptools` does (making it more
  clear to understand for beginners).
- Remove mentions to `distutils`, `transition to PEP 517` from
  `userguide/index`.
  - Instead the text is changed to have a more "introductory" tone.
- Remove mentions to `distutils` from the Quickstart.
- Remove `python2` from the intersphinx mapping - it was causing trouble
  redirecting glossary terms to Python2 docs, instead of Python3.
- Modify documentation about development mode to be more aligned with
  current practices (i.e. using `pip install -e .`)
  - In this process all documentation about running `setuptools` commands
    in `distutils` projects was moved to a new file in `docs/deprecated/running_commands.rst`

1 files changed, 25 insertions, 13 deletions

diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst
index 74e9b1e4..bfe8b1b7 100644
--- a/docs/userguide/index.rst
+++ b/docs/userguide/index.rst
@@ -2,22 +2,24 @@
 Building and Distributing Packages with Setuptools
 ==================================================
 
-``Setuptools`` is a collection of enhancements to the Python ``distutils``
-that allow developers to more easily build and
-distribute Python packages, especially ones that have dependencies on other
-packages.
+The first step towards sharing a Python library or program is to build a
+distribution package [#package-overload]_. This includes adding a set of
+additional files containing metadata and configuration to not only instruct
+``setuptools`` on how the distribution should be built but also
+to help installer (such as :pypi:`pip`) during the installation process.
 
-Packages built and distributed using ``setuptools`` look to the user like
-ordinary Python packages based on the ``distutils``.
+This document contains information to help Python developers through this
+process. Please check the :doc:`/userguide/quickstart` for an overview of
+the workflow.
 
-Transition to PEP517
-====================
+Also note that ``setuptools`` is what is know in the community as :pep:`build
+backend <517#terminology-and-goals>`, user facing interfaces are provided by tools
+such as :pypi:`pip` and :pypi:`build`. To use ``setuptools``, one must
+explicitly create a ``pyproject.toml`` file as described :doc:`/build_meta`.
 
-Since setuptools no longer serves as the default build tool, one must explicitly
-opt in (by providing a :file:`pyproject.toml` file) to use this library. The user
-facing part is provided by tools such as pip and
-backend interface is described :doc:`in this document <../build_meta>`. The
-quickstart provides an overview of the new workflow.
+
+Contents
+========
 
 .. toctree::
     :maxdepth: 1
@@ -35,3 +37,13 @@ quickstart provides an overview of the new workflow.
     commands
     functionalities_rewrite
     miscellaneous
+
+---
+
+.. rubric:: Notes
+
+.. [#package-overload]
+   A :term:`Distribution Package` is also referred in the Python community simply as "package"
+   Unfortunately, this jargon might be a bit confusing for new users because the term package
+   can also to refer any :term:`directory <package>` (or sub directory) used to organize
+   :term:`modules <module>` and auxiliary files.