Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Re-add documentation for formatting mypy --help text #19063

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.

Sign up for GitHub

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

Merged
merged 5 commits into from
May 10, 2025
Merged

Re-add documentation for formatting mypy --help text #19063

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
67274d2
fix #15555
wyattscarpenter May 9, 2025
882d38e
format better
wyattscarpenter May 9, 2025
cd3b6d0
don't need the mypy documentation documentation
wyattscarpenter May 9, 2025
49d469d
format style guide more nicely
wyattscarpenter May 9, 2025
289e700
this is actually the bare infinitive
wyattscarpenter May 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 21 additions & 2 deletions mypy/main.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -535,8 +535,27 @@ def add_invertible_flag(
# their `dest` prefixed with `special-opts:`, which will cause them to be
# parsed into the separate special_opts namespace object.

# Note: we have a style guide for formatting the mypy --help text. See
# https://github.com/python/mypy/wiki/Documentation-Conventions
# Our style guide for formatting the output of running `mypy --help`:
# Flags:
# 1. The flag help text should start with a capital letter but never end with a period.
# 2. Keep the flag help text brief -- ideally just a single sentence.
# 3. All flags must be a part of a group, unless the flag is deprecated or suppressed.
# 4. Avoid adding new flags to the "miscellaneous" groups -- instead add them to an
# existing group or, if applicable, create a new group. Feel free to move existing
# flags to a new group: just be sure to also update the documentation to match.
#
# Groups:
# 1. The group title and description should start with a capital letter.
# 2. The first sentence of a group description should be written in the bare infinitive.
# Tip: try substituting the group title and description into the following sentence:
# > {group_title}: these flags will {group_description}
# Feel free to add subsequent sentences that add additional details.
# 3. If you cannot think of a meaningful description for a new group, omit it entirely.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This reads like "feel free to add a group even if it doesn't convey any semantic meaning" which isn't a good advice IMO. Was it intended? Groups are, khm, groups, they are supposed to wrap several settings that have something in common, and that "something" should be easy to describe.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have no particular opinion. I suppose this is advice for group for which the programmer cannot think of further description beyond the name.

Never been a problem for me, but I suppose if someone is having trouble it's better to instruct them that the default should be nothing rather than something unhelpful.

# (E.g. see the "miscellaneous" sections).
# 4. The group description should end with a period (unless the last line is a link). If you
# do end the group description with a link, omit the 'http://' prefix. (Some links are too
# long and will break up into multiple lines if we include that prefix, so for consistency
# we omit the prefix on all links.)

general_group = parser.add_argument_group(title="Optional arguments")
general_group.add_argument(
Expand Down