Improve cli help somewhat

docs/source/command_line.rst

@@ -85,8 +85,9 @@ for full details, see :ref:`running-mypy`.
 
     This flag will add everything that matches ``.gitignore`` file(s) to :option:`--exclude`.
 
+.. _optional-arguments:
 
-Optional arguments
+Utility arguments
 ******************
 
 .. option:: -h, --help
@@ -764,7 +765,10 @@ of the above sections.
     :option:`mypy --help` output.
 
     Note: the exact list of flags enabled by running :option:`--strict` may change
-    over time.
+    over time. For this version of mypy, the list is:
+
+    .. include:: strict_list.rst
+
 
 .. option:: --disable-error-code
 
@@ -1032,6 +1036,70 @@ in developing or debugging mypy internals.
     cause mypy to type check the contents of ``temp.py`` instead of  ``original.py``,
     but error messages will still reference ``original.py``.
 
+.. _enabling-incomplete-experimental-features:
+
+Experimental features
+*****************************************
+
+.. option:: --enable-incomplete-feature {PreciseTupleTypes, InlineTypedDict}
+
+    Some features may require several mypy releases to implement, for example
+    due to their complexity, potential for backwards incompatibility, or
+    ambiguous semantics that would benefit from feedback from the community.
+    You can enable such features for early preview using this flag. Note that
+    it is not guaranteed that all features will be ultimately enabled by
+    default. In *rare cases* we may decide to not go ahead with certain
+    features.
+
+    List of currently incomplete/experimental features:
+
+    * ``PreciseTupleTypes``: this feature will infer more precise tuple types in
+      various scenarios. Before variadic types were added to the Python type system
+      by :pep:`646`, it was impossible to express a type like "a tuple with
+      at least two integers". The best type available was ``tuple[int, ...]``.
+      Therefore, mypy applied very lenient checking for variable-length tuples.
+      Now this type can be expressed as ``tuple[int, int, *tuple[int, ...]]``.
+      For such more precise types (when explicitly *defined* by a user) mypy,
+      for example, warns about unsafe index access, and generally handles them
+      in a type-safe manner. However, to avoid problems in existing code, mypy
+      does not *infer* these precise types when it technically can. Here are
+      notable examples where ``PreciseTupleTypes`` infers more precise types:
+
+      .. code-block:: python
+
+         numbers: tuple[int, ...]
+
+         more_numbers = (1, *numbers, 1)
+         reveal_type(more_numbers)
+         # Without PreciseTupleTypes: tuple[int, ...]
+         # With PreciseTupleTypes: tuple[int, *tuple[int, ...], int]
+
+         other_numbers = (1, 1) + numbers
+         reveal_type(other_numbers)
+         # Without PreciseTupleTypes: tuple[int, ...]
+         # With PreciseTupleTypes: tuple[int, int, *tuple[int, ...]]
+
+         if len(numbers) > 2:
+             reveal_type(numbers)
+             # Without PreciseTupleTypes: tuple[int, ...]
+             # With PreciseTupleTypes: tuple[int, int, int, *tuple[int, ...]]
+         else:
+             reveal_type(numbers)
+             # Without PreciseTupleTypes: tuple[int, ...]
+             # With PreciseTupleTypes: tuple[()] | tuple[int] | tuple[int, int]
+
+    * ``InlineTypedDict``: this feature enables non-standard syntax for inline
+      :ref:`TypedDicts <typeddict>`, for example:
+
+      .. code-block:: python
+
+         def test_values() -> {"foo": int, "bar": str}:
+             return {"foo": 42, "bar": "test"}
+
+.. 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.
 
 Report generation
 *****************
@@ -1093,65 +1161,6 @@ format into the specified directory.
     ``mypy[reports]``.
 
 
-Enabling incomplete/experimental features
-*****************************************
-
-.. option:: --enable-incomplete-feature {PreciseTupleTypes, InlineTypedDict}
-
-    Some features may require several mypy releases to implement, for example
-    due to their complexity, potential for backwards incompatibility, or
-    ambiguous semantics that would benefit from feedback from the community.
-    You can enable such features for early preview using this flag. Note that
-    it is not guaranteed that all features will be ultimately enabled by
-    default. In *rare cases* we may decide to not go ahead with certain
-    features.
-
-List of currently incomplete/experimental features:
-
-* ``PreciseTupleTypes``: this feature will infer more precise tuple types in
-  various scenarios. Before variadic types were added to the Python type system
-  by :pep:`646`, it was impossible to express a type like "a tuple with
-  at least two integers". The best type available was ``tuple[int, ...]``.
-  Therefore, mypy applied very lenient checking for variable-length tuples.
-  Now this type can be expressed as ``tuple[int, int, *tuple[int, ...]]``.
-  For such more precise types (when explicitly *defined* by a user) mypy,
-  for example, warns about unsafe index access, and generally handles them
-  in a type-safe manner. However, to avoid problems in existing code, mypy
-  does not *infer* these precise types when it technically can. Here are
-  notable examples where ``PreciseTupleTypes`` infers more precise types:
-
-  .. code-block:: python
-
-     numbers: tuple[int, ...]
-
-     more_numbers = (1, *numbers, 1)
-     reveal_type(more_numbers)
-     # Without PreciseTupleTypes: tuple[int, ...]
-     # With PreciseTupleTypes: tuple[int, *tuple[int, ...], int]
-
-     other_numbers = (1, 1) + numbers
-     reveal_type(other_numbers)
-     # Without PreciseTupleTypes: tuple[int, ...]
-     # With PreciseTupleTypes: tuple[int, int, *tuple[int, ...]]
-
-     if len(numbers) > 2:
-         reveal_type(numbers)
-         # Without PreciseTupleTypes: tuple[int, ...]
-         # With PreciseTupleTypes: tuple[int, int, int, *tuple[int, ...]]
-     else:
-         reveal_type(numbers)
-         # Without PreciseTupleTypes: tuple[int, ...]
-         # With PreciseTupleTypes: tuple[()] | tuple[int] | tuple[int, int]
-
-* ``InlineTypedDict``: this feature enables non-standard syntax for inline
-  :ref:`TypedDicts <typeddict>`, for example:
-
-  .. code-block:: python
-
-     def test_values() -> {"int": int, "str": str}:
-         return {"int": 42, "str": "test"}
-
-
 Miscellaneous
 *************
 
@@ -1198,11 +1207,6 @@ Miscellaneous
     type checking results. This can make it easier to integrate mypy
     with continuous integration (CI) tools.
 
-.. 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.
-
 .. option:: --scripts-are-modules
 
     This flag will give command line arguments that appear to be

docs/source/html_builder.py

@@ -11,16 +11,35 @@
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.environment import BuildEnvironment
 
+from mypy.main import define_options
+
 
 class MypyHTMLBuilder(StandaloneHTMLBuilder):
+    strict_file: Path
+
     def __init__(self, app: Sphinx, env: BuildEnvironment) -> None:
         super().__init__(app, env)
         self._ref_to_doc = {}
+        self.strict_file = Path(self.srcdir) / "strict_list.rst"
+        self._add_strict_list()
 
     def write_doc(self, docname: str, doctree: document) -> None:
         super().write_doc(docname, doctree)
         self._ref_to_doc.update({_id: docname for _id in doctree.ids})
 
+    def _add_strict_list(self) -> None:
+        strict_flags: list[str]
+        _, strict_flags, _ = define_options()
+        strict_part = ", ".join(f":option:`{s} <mypy {s}>`" for s in strict_flags)
+        if (
+            not strict_part
+            or strict_part.isspace()
+            or len(strict_part) < 20
+            or len(strict_part) > 2000
+        ):
+            raise ValueError(f"{strict_part=}, which doesn't look right (by a simple heuristic).")
+        self.strict_file.write_text(strict_part)
+
     def _verify_error_codes(self) -> None:
         from mypy.errorcodes import error_codes
 
@@ -55,6 +74,7 @@ def _write_ref_redirector(self) -> None:
     def finish(self) -> None:
         super().finish()
         self._write_ref_redirector()
+        self.strict_file.unlink()
 
 
 def setup(app: Sphinx) -> dict[str, Any]: