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, 0 insertions, 1 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 90286916..39fffceb 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -178,7 +178,6 @@ nitpick_ignore = [
 
 # Allow linking objects on other Sphinx sites seamlessly:
 intersphinx_mapping.update(
-    python2=('https://docs.python.org/2', None),
     python=('https://docs.python.org/3', None),
 )