-
-
Notifications
You must be signed in to change notification settings - Fork 30.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
gh-90300: Improve the Python CLI help output #115853
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
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 <merwok@netwok.org>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, much easier to review now :)
Looks good, a few suggestions.
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
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 <storchaka@gmail.com> Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
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 <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
…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 <storchaka@gmail.com> Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
…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 <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
* 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 <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
* 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 <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
* 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 <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
📚 Documentation preview 📚: https://cpython-previews--115853.org.readthedocs.build/