MNT: Ensure all types from matplotlib.typing are documented

Author: timhoffm

doc/api/typing_api.rst

@@ -6,6 +6,11 @@
    :no-members:
    :no-undoc-members:
 
+.. types are written out explicitly as `.. autodata::` directives, so that we
+   can meaningfully group them in sections.
+   test_typing.py::test_typing_aliases_documented ensures that the documented
+   types are in sync with the actual types defined in matplotlib.typing.
+
 Color
 =====
 
@@ -16,19 +21,42 @@ Color
 .. autodata:: matplotlib.typing.RGBColourType
 .. autodata:: matplotlib.typing.RGBAColourType
 
-Styles
-======
+Artist styles
+=============
 
 .. autodata:: matplotlib.typing.LineStyleType
 .. autodata:: matplotlib.typing.DrawStyleType
 .. autodata:: matplotlib.typing.MarkEveryType
+.. autodata:: matplotlib.typing.MarkerType
 .. autodata:: matplotlib.typing.FillStyleType
 .. autodata:: matplotlib.typing.CapStyleType
 .. autodata:: matplotlib.typing.JoinStyleType
 
+Events
+======
+
+.. autodata:: matplotlib.typing.MouseEventType
+.. autodata:: matplotlib.typing.KeyEventType
+.. autodata:: matplotlib.typing.DrawEventType
+.. autodata:: matplotlib.typing.PickEventType
+.. autodata:: matplotlib.typing.ResizeEventType
+.. autodata:: matplotlib.typing.CloseEventType
+.. autodata:: matplotlib.typing.EventType
+
+rcParams and stylesheets
+========================
+.. autodata:: matplotlib.typing.RcKeyType
+.. autodata:: matplotlib.typing.RcGroupKeyType
+.. autodata:: matplotlib.typing.RcStyleType
+
 Other types
 ===========
 
 .. autodata:: matplotlib.typing.CoordsType
-.. autodata:: matplotlib.typing.RcStyleType
+.. autodata:: matplotlib.typing.LegendLocType
+.. autodata:: matplotlib.typing.LogLevel
 .. autodata:: matplotlib.typing.HashableList
+
+
+.. intentionally undocumented types (one type per row)
+   CoordsBaseType

lib/matplotlib/tests/test_typing.py

@@ -34,6 +34,70 @@ def test_cm_stub_matches_runtime_colormaps():
     assert runtime_cmaps == stubbed_cmaps
 
 
+def test_typing_aliases_documented():
+    """Every public type in typing.py is documented or intentionally undocumented."""
+    import ast
+
+    typing_py_path = Path(__file__).parent.parent / "typing.py"
+    assert typing_py_path.exists(), f"{typing_py_path} does not exist"
+    tree = ast.parse(typing_py_path.read_text(encoding="utf-8"))
+
+    # Collect all public module-level assignment names (both annotated and plain).
+    defined_types = set()
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            name = node.target.id
+        elif isinstance(node, ast.Assign) and len(node.targets) == 1:
+            target = node.targets[0]
+            name = target.id if isinstance(target, ast.Name) else None
+        else:
+            continue
+        if name is not None and not name.startswith("_"):
+            defined_types.add(name)
+
+    assert defined_types, "No type definitions found in typing.py"
+
+    rst_path = (
+        Path(__file__).parent.parent.parent.parent / "doc" / "api" / "typing_api.rst"
+    )
+    assert rst_path.exists(), f"{rst_path} does not exist"
+    rst_content = rst_path.read_text(encoding="utf-8")
+
+    # Collect documented ``.. autodata::`` entries.
+    documented = set(
+        re.findall(
+            r"^\.\.\s+autodata::\s+matplotlib\.typing\.(\w+)",
+            rst_content,
+            re.MULTILINE,
+        )
+    )
+    assert documented, "No autodata entries found in typing_api.rst"
+
+    # Collect types listed under the comment
+    # ".. intentionally undocumented types (one type per row)".
+    # Each type must be indented and an empty line ends the section.
+    intentionally_undocumented = set()
+    marker = ".. intentionally undocumented types (one type per row)"
+    lines_following_marker = rst_content.split(marker, 1)[1].splitlines()[1:]
+    for line in lines_following_marker:
+        if not line or not line[0].isspace():
+            break
+        intentionally_undocumented.add(line.strip())
+
+    accounted_for = documented | intentionally_undocumented
+
+    missing = defined_types - accounted_for
+    assert not missing, (
+        f"Types defined in typing.py but not in typing_api.rst "
+        f"(document them or add to 'intentionally undocumented types'): {missing}"
+    )
+
+    extra = accounted_for - defined_types
+    assert not extra, (
+        f"Types listed in typing_api.rst but not defined in typing.py: {extra}"
+    )
+
+
 def test_rcparam_stubs():
     runtime_rc_keys = {
         name for name in plt.rcParamsDefault.keys()

lib/matplotlib/typing.py

@@ -116,6 +116,10 @@
     pathlib.Path |
     Sequence[str | pathlib.Path | dict[str, Any]]
 )
+"""
+Valid specifiers for styles as used in `matplotlib.style.use` and
+`matplotlib.style.context`.
+"""
 
 _HT = TypeVar("_HT", bound=Hashable)
 HashableList: TypeAlias = list[_HT | "HashableList[_HT]"]
@@ -170,6 +174,12 @@
     tuple[float, float] |
     int
 )
+"""
+Supported location specifiers for legends.
+
+This is a superset of permissible entries. "best" is only applicable to Axes legends.
+All the "outside ..." locations are only applicable to figure legends.
+"""
 
 RcKeyType: TypeAlias = Literal[
     "agg.path.chunksize",