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`

2 files changed, 24 insertions, 0 deletions

diff --git a/docs/deprecated/index.rst b/docs/deprecated/index.rst
index 8169b3b7..620de332 100644
--- a/docs/deprecated/index.rst
+++ b/docs/deprecated/index.rst
@@ -19,3 +19,4 @@ objectives.
     distutils/index
     distutils-legacy
     functionalities
+    running_commands
diff --git a/docs/deprecated/running_commands.rst b/docs/deprecated/running_commands.rst
new file mode 100644
index 00000000..862f5fee
--- /dev/null
+++ b/docs/deprecated/running_commands.rst
@@ -0,0 +1,23 @@
+Running ``setuptools`` commands
+===============================
+
+Historically, ``setuptools`` allowed running commands via a ``setup.py`` script
+at the root of a Python project, as indicated in the examples below::
+
+    python setup.py --help
+    python setup.py --help-commands
+    python setup.py --version
+    python setup.py sdist
+    python setup.py bdist_wheel
+
+You could also run commands in other circumstances:
+
+* ``setuptools`` projects without ``setup.py`` (e.g. ``setup.cfg``-only)::
+
+   python -c "import setuptools; setup()" --help
+
+* ``distutils`` projects (with a ``setup.py`` importing ``distutils``)::
+
+   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.