Merge pull request matplotlib#29918 from timhoffm/doc-typing

DOC: Add descriptions to matplotlib.typing

Author: timhoffm

doc/api/typing_api.rst

@@ -2,18 +2,33 @@
 ``matplotlib.typing``
 *********************
 
+.. automodule:: matplotlib.typing
+   :no-members:
+   :no-undoc-members:
+
+Color
+=====
+
+.. autodata:: matplotlib.typing.ColorType
 .. autodata:: matplotlib.typing.RGBColorType
-.. autodata:: matplotlib.typing.RGBColourType
 .. autodata:: matplotlib.typing.RGBAColorType
-.. autodata:: matplotlib.typing.RGBAColourType
-.. autodata:: matplotlib.typing.ColorType
 .. autodata:: matplotlib.typing.ColourType
+.. autodata:: matplotlib.typing.RGBColourType
+.. autodata:: matplotlib.typing.RGBAColourType
+
+Styles
+======
+
 .. autodata:: matplotlib.typing.LineStyleType
 .. autodata:: matplotlib.typing.DrawStyleType
 .. autodata:: matplotlib.typing.MarkEveryType
 .. autodata:: matplotlib.typing.FillStyleType
 .. autodata:: matplotlib.typing.CapStyleType
 .. autodata:: matplotlib.typing.JoinStyleType
+
+Other types
+===========
+
+.. autodata:: matplotlib.typing.CoordsType
 .. autodata:: matplotlib.typing.RcStyleType
 .. autodata:: matplotlib.typing.HashableList
-   :annotation: Nested list with Hashable values

lib/matplotlib/typing.py

@@ -4,7 +4,8 @@
 This module contains Type aliases which are useful for Matplotlib and potentially
 downstream libraries.
 
-.. admonition:: Provisional status of typing
+.. warning::
+    **Provisional status of typing**
 
     The ``typing`` module and type stub files are considered provisional and may change
     at any time without a deprecation period.
@@ -21,6 +22,8 @@
 from .transforms import Bbox, Transform
 
 RGBColorType: TypeAlias = tuple[float, float, float] | str
+"""Any RGB color specification accepted by Matplotlib."""
+
 RGBAColorType: TypeAlias = (
     str |  # "none" or "#RRGGBBAA"/"#RGBA" hex strings
     tuple[float, float, float, float] |
@@ -30,31 +33,55 @@
     # (4-tuple, float) is odd, but accepted as the outer float overriding A of 4-tuple
     tuple[tuple[float, float, float, float], float]
 )
+"""Any RGBA color specification accepted by Matplotlib."""
 
 ColorType: TypeAlias = RGBColorType | RGBAColorType
+"""Any color specification accepted by Matplotlib. See :mpltype:`color`."""
 
 RGBColourType: TypeAlias = RGBColorType
+"""Alias of `.RGBColorType`."""
+
 RGBAColourType: TypeAlias = RGBAColorType
+"""Alias of `.RGBAColorType`."""
+
 ColourType: TypeAlias = ColorType
+"""Alias of `.ColorType`."""
 
 LineStyleType: TypeAlias = (
     Literal["-", "solid", "--", "dashed", "-.", "dashdot", ":", "dotted",
             "", "none", " ", "None"] |
     tuple[float, Sequence[float]]
 )
+"""
+Any line style specification accepted by Matplotlib.
+See :doc:`/gallery/lines_bars_and_markers/linestyles`.
+"""
+
 DrawStyleType: TypeAlias = Literal["default", "steps", "steps-pre", "steps-mid",
                                    "steps-post"]
+"""See :doc:`/gallery/lines_bars_and_markers/step_demo`."""
+
 MarkEveryType: TypeAlias = (
     None |
     int | tuple[int, int] | slice | list[int] |
     float | tuple[float, float] |
     list[bool]
 )
+"""See :doc:`/gallery/lines_bars_and_markers/markevery_demo`."""
 
 MarkerType: TypeAlias = str | path.Path | MarkerStyle
+"""
+Marker specification. See :doc:`/gallery/lines_bars_and_markers/marker_reference`.
+"""
+
 FillStyleType: TypeAlias = Literal["full", "left", "right", "bottom", "top", "none"]
+"""Marker fill styles. See :doc:`/gallery/lines_bars_and_markers/marker_reference`."""
+
 JoinStyleType: TypeAlias = JoinStyle | Literal["miter", "round", "bevel"]
+"""Line join styles. See :doc:`/gallery/lines_bars_and_markers/joinstyle`."""
+
 CapStyleType: TypeAlias = CapStyle | Literal["butt", "projecting", "round"]
+"""Line cap styles. See :doc:`/gallery/lines_bars_and_markers/capstyle`."""
 
 CoordsBaseType = Union[
     str,