Improve docs by avoiding confusion with distutils#3363
Merged
abravalheri merged 3 commits intopypa:mainfrom Jun 13, 2022
Merged
Improve docs by avoiding confusion with distutils#3363abravalheri merged 3 commits intopypa:mainfrom
abravalheri merged 3 commits intopypa:mainfrom
Conversation
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`
Contributor
Author
|
@codeandfire what do you think about these changes? 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... |
Contributor
|
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. |
Contributor
Author
|
Thank you very much @codeandfire, that is very kind! |
abravalheri
commented
Jun 13, 2022
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
distutilsis in the process of being adopted bysetuptools, the documentation should be changed to minimize mentions todistutilsand 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
setuptoolsdoes (making it more clear to understand for beginners).distutils,transition to PEP 517fromuserguide/index.distutilsfrom the Quickstart.python2from the intersphinx mapping - it was causing trouble redirecting glossary terms to Python2 docs, instead of Python3.pip install -e .)setuptoolscommands indistutilsprojects was moved to a new file indocs/deprecated/running_commands.rstSide 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
changelog.d/.(See documentation for details)