gh-90300: Improve the Python CLI help output #115853
Conversation
* document equivalent command-line options for all environment variables * document equivalent environment variables for all command-line options * reduce the size of variable and option descriptions to minimum * sort the lists of -X options and variables that have equivalent command-line options * remove the ending period in single-sentence descriptions
serhiy-storchaka
added
skip news
needs backport to 3.11
|
The CLI help should be short. It is a list of options and environment variables with short descriptions to have some idea what they are about. Ideally, every option description should be a single line. If you want to learn details, you should read the documentation. The CLI help is just to remind you exact names and format of some options and environment variables. |
|
I’m not sure if I agree with that, or if it’s the consensus within python-dev. |
|
What can be done so that this PR does not hang for another 2 years like #93415? It is painful and errorprone to resolve merge conflicts after adding new options and environment variables. |
|
@erlend-aasland, @AlexWaygood and @hugovk agree with you on the ticket. To me this needed a little discussion – I don’t think that there is a current agreement that help should be more concise than (relatively) comprehensive. But this is only an interpreter option, not the public API, so it would be fine to follow EAFP and go ahead! And it’s true that people probably use the online docs more than the command-line, and that we have help texts duplicated in three places – one removed with this change. 🚀 |
|
There's always the possibility of opening a topic on Discourse, so we can have a broader discussion. I think I want to read up some more on the CLI guide Hugo linked to in the issue, before I decide. |
|
FTR, this is a follow-up to gh-93415. |
|
It would be easier to review if the bullet points were in split into separate (followup) PRs. For example:
I think I could review and approve those as a single PR immediately, and it'd make followups smaller and easier (and quicker 🤞) to review. |
|
The part of the problem is that not for all options and variables the equivalent is currently specified, and that there are two lists for environment variables. So the change may require adding references to options and variables (which may increase the size of the description, and may not fit the style of the verbose description) and moving variables from one list to other. Is it okay? |
|
See #116739 for a simple step. |
|
Next step: #116756. |
|
Next step: #116765. |
Co-authored-by: Éric <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
|
Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12. |
|
Sorry, @serhiy-storchaka, I could not cleanly backport this to |
|
Sorry, @serhiy-storchaka, I could not cleanly backport this to |
…15853) * document equivalent command-line options for all environment variables * document equivalent environment variables for all command-line options * reduce the size of variable and option descriptions to minimum * remove the ending period in single-sentence descriptions (cherry picked from commit b85572c) Co-authored-by: Serhiy Storchaka <[email protected]> Co-authored-by: Éric <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]>
|
GH-117022 is a backport of this pull request to the 3.12 branch. |
…17022) * document equivalent command-line options for all environment variables * document equivalent environment variables for all command-line options * reduce the size of variable and option descriptions to minimum * remove the ending period in single-sentence descriptions (cherry picked from commit b85572c) Co-authored-by: Éric <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]>
…honGH-115853) (pythonGH-117022) * document equivalent command-line options for all environment variables * document equivalent environment variables for all command-line options * reduce the size of variable and option descriptions to minimum * remove the ending period in single-sentence descriptions (cherry picked from commit b85572c) (cherry picked from commit 4be9fa8) Co-authored-by: Serhiy Storchaka <[email protected]> Co-authored-by: Éric <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]>
…17022) (GH-117034) * document equivalent command-line options for all environment variables * document equivalent environment variables for all command-line options * reduce the size of variable and option descriptions to minimum * remove the ending period in single-sentence descriptions (cherry picked from commit b85572c) (cherry picked from commit 4be9fa8) Co-authored-by: Éric <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]>
* document equivalent command-line options for all environment variables * document equivalent environment variables for all command-line options * reduce the size of variable and option descriptions to minimum * remove the ending period in single-sentence descriptions Co-authored-by: Éric <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]>
* document equivalent command-line options for all environment variables * document equivalent environment variables for all command-line options * reduce the size of variable and option descriptions to minimum * remove the ending period in single-sentence descriptions Co-authored-by: Éric <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]>
* document equivalent command-line options for all environment variables * document equivalent environment variables for all command-line options * reduce the size of variable and option descriptions to minimum * remove the ending period in single-sentence descriptions Co-authored-by: Éric <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]>
📚 Documentation preview 📚: https://cpython-previews--115853.org.readthedocs.build/