DOC: Improve widgets API documentation

timhoffm · timhoffm · commit def8e73f54a1 · 2026-01-15T15:18:31.000+01:00
- Structure the page into widgets and helpers.
  This requires explicit listing of the classes, but is bearable as we
  don't often add new classes
- Limit the inheritance diagram to the Widget subclasses instead of also
 showning the helper classes there
- Add documentation for `_SelectorWidget`. It's important to understand
its subclasses. This also results in correctly showing the selector
inheritance in the inheritance diagram
diff --git a/doc/api/widgets_api.rst b/doc/api/widgets_api.rst
@@ -2,11 +2,53 @@
 ``matplotlib.widgets``
 **********************
 
-.. inheritance-diagram:: matplotlib.widgets
+.. currentmodule:: matplotlib.widgets
+
+.. automodule:: matplotlib.widgets
+   :no-members:
+   :no-undoc-members:
+
+
+Widget classes
+==============
+
+.. inheritance-diagram:: matplotlib.widgets.Widget
    :parts: 1
+   :private-bases:
+   :include-subclasses:
 
+.. autosummary::
+   :toctree: _as_gen
+   :template: autosummary.rst
+   :nosignatures:
 
-.. automodule:: matplotlib.widgets
-   :members:
-   :undoc-members:
-   :show-inheritance:
+   Widget
+   AxesWidget
+   Cursor
+   MultiCursor
+   Button
+   CheckButtons
+   RadioButtons
+   SliderBase
+   Slider
+   RangeSlider
+   TextBox
+   _SelectorWidget
+   RectangleSelector
+   EllipseSelector
+   Lasso
+   LassoSelector
+   PolygonSelector
+   SpanSelector
+   SubplotTool
+
+Helper classes
+==============
+
+.. autosummary::
+   :toctree: _as_gen
+   :nosignatures:
+
+   LockDraw
+   ToolHandles
+   ToolLineHandles
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -1,8 +1,6 @@
 """
-GUI neutral widgets
-===================
-
 Widgets that are designed to work for any of the GUI backends.
+
 All of these widgets require you to predefine an `~.axes.Axes`
 instance and pass that as the first parameter.  Matplotlib doesn't try to
 be too smart with respect to layout -- you will have to figure out how
@@ -2193,6 +2191,16 @@ def onmove(self, event):
 
 
 class _SelectorWidget(AxesWidget):
+    """
+    The base class for selector widgets.
+
+    This class provides common functionality for selector widgets,
+    such as handling mouse and keyboard events, managing state modifier keys, etc.
+
+    The class itself is private and may be changed or removed without prior warning.
+    However, the public API it provides to subclasses is stable and considered
+    public on the subclasses.
+    """
 
     def __init__(self, ax, onselect=None, useblit=False, button=None,
                  state_modifier_keys=None, use_data_coordinates=False):
@@ -2497,7 +2505,7 @@ def set_props(self, **props):
     def set_handle_props(self, **handle_props):
         """
         Set the properties of the handles selector artist. See the
-        `handle_props` argument in the selector docstring to know which
+        *handle_props* argument in the selector docstring to know which
         properties are supported.
         """
         if not hasattr(self, '_handles_artists'):
@@ -2521,13 +2529,15 @@ def _validate_state(self, state):
     def add_state(self, state):
         """
         Add a state to define the widget's behavior. See the
-        `state_modifier_keys` parameters for details.
+        *state_modifier_keys* parameter in the constructor of the concrete
+        selector class for details.
 
         Parameters
         ----------
         state : str
             Must be a supported state of the selector. See the
-            `state_modifier_keys` parameters for details.
+            *state_modifier_keys* parameter in the constructor of the concrete
+            selector class for details.
 
         Raises
         ------
@@ -2541,13 +2551,15 @@ def add_state(self, state):
     def remove_state(self, state):
         """
         Remove a state to define the widget's behavior. See the
-        `state_modifier_keys` parameters for details.
+        *state_modifier_keys* parameter in the constructor of the concrete
+        selector class for details.
 
         Parameters
         ----------
         state : str
             Must be a supported state of the selector. See the
-            `state_modifier_keys` parameters for details.
+            *state_modifier_keys* parameter in the constructor of the concrete
+            selector class for details.
 
         Raises
         ------
