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

wyattscarpenter · web-flow · commit 18a66959c4ac · 2025-05-10T16:19:21.000-07:00
Fixes #15555 This re-adds some rather-innocuous documentation to main about how to write command line flag descriptions, which were on a wiki page that was subsequently destroyed (rendering the link in the comment dead).
diff --git a/mypy/main.py b/mypy/main.py
@@ -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.
+    #     (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(
