Improve docs by avoiding confusion with distutils

[abravalheri]

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.

This PR is not exhaustive and do not implement all the necessary changes to achieve this view, and it is likely that many follow up PRs would be required.

Summary of 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

Side note: I believe that in the future we can also start adopting some practices as described by the diataxis framework (e.g. strive to create/separate the documentation with different target audiences in mind, as pointed out in this discussion.

Pull Request Checklist

• Changes have tests
• News fragment added in changelog.d/.
  (See documentation for details)

[abravalheri]

@codeandfire what do you think about these changes?
I am trying to make the docs easier to understand for beginners (that don't necessarily have knowledge about distutils). It is a big journey, so this is only the first step.

In the future, it would be nice if we manage to include some tutorials and start separating things in "howtos"... But that is another journey...

[codeandfire]

Hi @abravalheri, I think it's a great step! The current changes are really good, and especially the changes made to the Development Mode page in itself resolve a large part of the confusion. I am ready to contribute to any future efforts involving creating tutorials/howtos etc. to make it easier for beginners.

[abravalheri]

Thank you very much @codeandfire, that is very kind!