Improve cli help somewhat, creating an Experimental group

docs/source/command_line.rst

@@ -1156,7 +1156,9 @@ format into the specified directory.
     ``mypy[reports]``.
 
 
-Enabling incomplete/experimental features
+.. _enabling-incomplete-experimental-features:
+
+Experimental features
 *****************************************
 
 .. option:: --enable-incomplete-feature {PreciseTupleTypes,InlineTypedDict,TypeForm}
@@ -1217,6 +1219,11 @@ List of currently incomplete/experimental features:
 * ``TypeForm``: this feature enables ``TypeForm``, as described in
   `PEP 747 – Annotating Type Forms <https://peps.python.org/pep-0747/>_`.
 
+.. option:: --find-occurrences CLASS.MEMBER
+
+    This flag will make mypy print out all usages of a class member
+    based on static type information. This feature is experimental.
+
 
 Miscellaneous
 *************

docs/source/html_builder.py

@@ -39,7 +39,7 @@ def _add_strict_list(self) -> None:
         ):
             raise ValueError(f"{strict_part=}, which doesn't look right (by a simple heuristic).")
         self.strict_file.write_text(
-            "For this version of mypy, the list of flags enabled by strict is: " + strict_part
+            "For this version of mypy, the flags enabled by strict are: " + strict_part
         )
 
     def _verify_error_codes(self) -> None:

mypy/main.py

@@ -1115,12 +1115,6 @@ def add_invertible_flag(
     internals_group.add_argument(
         "--disable-expression-cache", action="store_true", help=argparse.SUPPRESS
     )
-    parser.add_argument(
-        "--enable-incomplete-feature",
-        action="append",
-        metavar="{" + ",".join(sorted(INCOMPLETE_FEATURES)) + "}",
-        help="Enable support of incomplete/experimental features for early preview",
-    )
     internals_group.add_argument(
         "--custom-typeshed-dir", metavar="DIR", help="Use the custom typeshed in DIR"
     )
@@ -1173,6 +1167,28 @@ def add_invertible_flag(
         "--skip-c-gen", dest="mypyc_skip_c_generation", action="store_true", help=argparse.SUPPRESS
     )
 
+    experimental_group = parser.add_argument_group(
+        title="Experimental options",
+        description="Enable features that work well enough to be useful,"
+        + " but perhaps not as well as you might wish."
+        + " These features may be enabled by default in the future,"
+        + " or may be made non-experimental."
+        + " Experimental features that are better described in some other context"
+        + " may be documented in some other place instead.",
+    )
+    experimental_group.add_argument(
+        "--enable-incomplete-feature",
+        action="append",
+        metavar="{" + ",".join(sorted(INCOMPLETE_FEATURES)) + "}",
+        help="Enable support of incomplete/experimental features for early preview",
+    )
+    experimental_group.add_argument(
+        "--find-occurrences",
+        metavar="CLASS.MEMBER",
+        dest="special-opts:find_occurrences",
+        help="Print out all usages of a class member",
+    )
+
     misc_group = parser.add_argument_group(title="Miscellaneous")
     misc_group.add_argument("--quickstart-file", help=argparse.SUPPRESS)
     misc_group.add_argument(
@@ -1186,12 +1202,6 @@ def add_invertible_flag(
         default="global",
         help="If --junit-xml is set, specifies format. global (default): single test with all errors; per_file: one test entry per file with failures",
     )
-    misc_group.add_argument(
-        "--find-occurrences",
-        metavar="CLASS.MEMBER",
-        dest="special-opts:find_occurrences",
-        help="Print out all usages of a class member (experimental)",
-    )
     misc_group.add_argument(
         "--scripts-are-modules",
         action="store_true",
@@ -1549,7 +1559,8 @@ def set_strict_flags() -> None:
                 reason = cache.find_module(p)
                 if reason is ModuleNotFoundReason.FOUND_WITHOUT_TYPE_HINTS:
                     fail(
-                        f"Package '{p}' cannot be type checked due to missing py.typed marker. See https://mypy.readthedocs.io/en/stable/installed_packages.html for more details",
+                        f"Package '{p}' cannot be type checked due to missing py.typed marker."
+                        + " See https://mypy.readthedocs.io/en/stable/installed_packages.html for more details",
                         stderr,
                         options,
                     )