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`

3 files changed, 45 insertions, 53 deletions

diff --git a/docs/userguide/development_mode.rst b/docs/userguide/development_mode.rst
index 90bc5676..822ee4f8 100644
--- a/docs/userguide/development_mode.rst
+++ b/docs/userguide/development_mode.rst
@@ -1,13 +1,13 @@
 "Development Mode"
 ==================
 
-Under normal circumstances, the ``distutils`` assume that you are going to
+Under normal circumstances, the ``setuptools`` assume that you are going to
 build a distribution of your project, not use it in its "raw" or "unbuilt"
-form.  However, if you were to use the ``distutils`` to build a distribution,
+form.  However, if you were to use the ``setuptools`` to build a distribution,
 you would have to rebuild and reinstall your project every time you made a
 change to it during development.
 
-Another problem that sometimes comes up with the ``distutils`` is that you may
+Another problem that sometimes comes is that you may
 need to do development on two related projects at the same time.  You may need
 to put both projects' packages in the same directory to run them, but need to
 keep them separate for revision control purposes.  How can you do this?
@@ -15,38 +15,20 @@ keep them separate for revision control purposes.  How can you do this?
 Setuptools allows you to deploy your projects for use in a common directory or
 staging area, but without copying any files.  Thus, you can edit each project's
 code in its checkout directory, and only need to run build commands when you
-change a project's C extensions or similarly compiled files.  You can even
-deploy a project into another project's checkout directory, if that's your
-preferred way of working (as opposed to using a common independent staging area
-or the site-packages directory).
-
-To do this, use the ``setup.py develop`` command.  It works very similarly to
-``setup.py install``, except that it doesn't actually install anything.
-Instead, it creates a special ``.egg-link`` file in the deployment directory,
-that links to your project's source code.  And, if your deployment directory is
-Python's ``site-packages`` directory, it will also update the
-``easy-install.pth`` file to include your project's source code, thereby making
+change files that need to be compiled or the provided metadata and setuptools configuration.
+
+You can perform a ``pip`` installation passing the ``-e/--editable``
+flag (e.g. ``pip install -e .``). It works very similarly to
+``pip install .``, except that it doesn't actually install anything.
+Instead, it creates a special ``.egg-link`` file in the target directory
+(usually ``site-packages``) that links to your project's source code.
+It may also update an existing ``easy-install.pth`` file
+to include your project's source code, thereby making
 it available on ``sys.path`` for all programs using that Python installation.
 
-In addition, the ``develop`` command creates wrapper scripts in the target
-script directory that will run your in-development scripts after ensuring that
-all your ``install_requires`` packages are available on ``sys.path``.
-
 You can deploy the same project to multiple staging areas, e.g. if you have
 multiple projects on the same machine that are sharing the same project you're
 doing development work.
 
-When you're done with a given development task, you can remove the project
-source from a staging area using ``setup.py develop --uninstall``, specifying
-the desired staging area if it's not the default.
-
-There are several options to control the precise behavior of the ``develop``
-command; see the section on the :ref:`develop <develop>` command below for more details.
-
-Note that you can also apply setuptools commands to non-setuptools projects,
-using commands like this::
-
-   python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop
-
-That is, you can simply list the normal setup commands and options following
-the quoted part.
+When you're done with a given development task, you can simply uninstall your
+package (as you would normally do with ``pip uninstall <package name>``).
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.
diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst
index c4757b98..0b759473 100644
--- a/docs/userguide/quickstart.rst
+++ b/docs/userguide/quickstart.rst
@@ -1,6 +1,6 @@
-==========================
-``setuptools`` Quickstart
-==========================
+==========
+Quickstart
+==========
 
 Installation
 ============
@@ -286,10 +286,8 @@ For more advanced use, see :doc:`dependency_management`.
 
 Including Data Files
 ====================
-The distutils have traditionally allowed installation of "data files", which
-are placed in a platform-specific location. Setuptools offers three ways to
-specify data files to be included in your packages. For the simplest use, you
-can simply use the ``include_package_data`` keyword:
+Setuptools offers three ways to specify data files to be included in your packages.
+For the simplest use, you can simply use the ``include_package_data`` keyword:
 
 .. tab:: setup.cfg
 
@@ -319,7 +317,7 @@ can simply use the ``include_package_data`` keyword:
         # You can deactivate that with `include-package-data = false`
 
 This tells setuptools to install any data files it finds in your packages.
-The data files must be specified via the distutils' |MANIFEST.in|_ file
+The data files must be specified via the |MANIFEST.in|_ file
 or automatically added by a :ref:`Revision Control System plugin
 <Adding Support for Revision Control Systems>`.
 For more details, see :doc:`datafiles`.