Merge pull request matplotlib#20164 from anntzer/autokwdoc

Auto-generate required kwdoc entries into docstring.interpd.

Author: jklymak

doc/devel/documenting_mpl.rst

@@ -658,26 +658,14 @@ are:
 2. as automated as possible so that as properties change, the docs
    are updated automatically.
 
-The function `matplotlib.artist.kwdoc` and the decorator
-``matplotlib.docstring.dedent_interpd`` facilitate this.  They combine Python
-string interpolation in the docstring with the Matplotlib artist introspection
-facility that underlies ``setp`` and ``getp``.  The ``kwdoc`` function gives
-the list of properties as a docstring. In order to use this in another
-docstring, first update the ``matplotlib.docstring.interpd`` object, as seen in
-this example from `matplotlib.lines`:
-
-.. code-block:: python
-
-  # in lines.py
-  docstring.interpd.update(Line2D_kwdoc=artist.kwdoc(Line2D))
-
-Then in any function accepting `~.Line2D` pass-through ``kwargs``, e.g.,
-`matplotlib.axes.Axes.plot`:
+The ``@docstring.interpd`` decorator implements this.  Any function accepting
+`.Line2D` pass-through ``kwargs``, e.g., `matplotlib.axes.Axes.plot`, can list
+a summary of the `.Line2D` properties, as follows:
 
 .. code-block:: python
 
   # in axes.py
-  @docstring.dedent_interpd
+  @docstring.interpd
   def plot(self, *args, **kwargs):
       """
       Some stuff omitted
@@ -702,17 +690,19 @@ Then in any function accepting `~.Line2D` pass-through ``kwargs``, e.g.,
 
           Here is a list of available `.Line2D` properties:
 
-          %(Line2D_kwdoc)s
-
+          %(Line2D:kwdoc)s
       """
 
-Note there is a problem for `~matplotlib.artist.Artist` ``__init__`` methods,
-e.g., `matplotlib.patches.Patch`, which supports ``Patch`` ``kwargs``,
-since the artist inspector cannot work until the class is fully defined and
-we can't modify the ``Patch.__init__.__doc__`` docstring outside the class
-definition.  There are some some manual hacks in this case, violating the
-"single entry point" requirement above -- see the ``docstring.interpd.update``
-calls in `matplotlib.patches`.
+The ``%(Line2D:kwdoc)`` syntax makes ``interpd`` lookup an `.Artist` subclass
+named ``Line2D``, and call `.artist.kwdoc` on that class.  `.artist.kwdoc`
+introspects the subclass and summarizes its properties as a substring, which
+gets interpolated into the docstring.
+
+Note that this scheme does not work for decorating an Artist's ``__init__``, as
+the subclass and its properties are not defined yet at that point.  Instead,
+``@docstring.interpd`` can be used to decorate the class itself -- at that
+point, `.kwdoc` can list the properties and interpolate them into
+``__init__.__doc__``.
 
 
 Inheriting docstrings

doc/missing-references.json

@@ -14,16 +14,15 @@
       "lib/matplotlib/ticker.py:docstring of matplotlib.ticker.LogitLocator.tick_values:5",
       "lib/matplotlib/ticker.py:docstring of matplotlib.ticker.MaxNLocator.tick_values:5",
       "lib/matplotlib/ticker.py:docstring of matplotlib.ticker.MultipleLocator.tick_values:5",
-      "lib/matplotlib/ticker.py:docstring of matplotlib.ticker.OldAutoLocator.tick_values:5",
       "lib/matplotlib/ticker.py:docstring of matplotlib.ticker.SymmetricalLogLocator.tick_values:5"
     ],
     "button": [
       "doc/users/prev_whats_new/whats_new_3.1.0.rst:335"
     ],
     "cbar_axes": [
-      "lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid.__init__:49",
-      "lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid:49",
-      "lib/mpl_toolkits/axisartist/axes_grid.py:docstring of mpl_toolkits.axisartist.axes_grid.ImageGrid:49"
+      "lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid.__init__:45",
+      "lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid:45",
+      "lib/mpl_toolkits/axisartist/axes_grid.py:docstring of mpl_toolkits.axisartist.axes_grid.ImageGrid:45"
     ],
     "eventson": [
       "lib/matplotlib/widgets.py:docstring of matplotlib.widgets.CheckButtons.set_active:4",
@@ -574,6 +573,26 @@
     "get_matrix": [
       "lib/matplotlib/transforms.py:docstring of matplotlib.transforms.Affine2DBase:13"
     ],
+    "matplotlib.collections._CollectionWithSizes.set_sizes": [
+      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.barbs:172",
+      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.broken_barh:82",
+      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.fill_between:112",
+      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.fill_betweenx:112",
+      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.hexbin:168",
+      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.pcolor:165",
+      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.quiver:202",
+      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.barbs:172",
+      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.broken_barh:82",
+      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.fill_between:112",
+      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.fill_betweenx:112",
+      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.hexbin:168",
+      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.pcolor:165",
+      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.quiver:202",
+      "lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Barbs.__init__:176",
+      "lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Barbs:206",
+      "lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Quiver.__init__:206",
+      "lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Quiver:239"
+    ],
     "matplotlib.dates.DateFormatter.__call__": [
       "doc/users/prev_whats_new/whats_new_1.5.rst:497"
     ],
@@ -594,11 +613,6 @@
     "dateutil": [
       "lib/matplotlib/dates.py:docstring of matplotlib.dates:1"
     ],
-    "matplotlib": [
-      "doc/api/next_api_changes/deprecations/19517-AL.rst:3",
-      "doc/api/prev_api_changes/api_changes_0.91.2.rst:15",
-      "doc/api/prev_api_changes/api_changes_3.4.0/deprecations.rst:58"
-    ],
     "matplotlib.ft2font": [
       "doc/api/prev_api_changes/api_changes_0.91.0.rst:34"
     ]
@@ -669,9 +683,6 @@
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.violinplot:46",
       "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.violinplot:46"
     ],
-    "Glue": [
-      "lib/matplotlib/mathtext.py:docstring of matplotlib.mathtext.GlueSpec:2"
-    ],
     "Glyph": [
       "doc/gallery/misc/ftface_props.rst:25"
     ],
@@ -716,9 +727,9 @@
       "doc/users/event_handling.rst:179"
     ],
     "Size.from_any": [
-      "lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid.__init__:61",
-      "lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid:61",
-      "lib/mpl_toolkits/axisartist/axes_grid.py:docstring of mpl_toolkits.axisartist.axes_grid.ImageGrid:61"
+      "lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid.__init__:57",
+      "lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid:57",
+      "lib/mpl_toolkits/axisartist/axes_grid.py:docstring of mpl_toolkits.axisartist.axes_grid.ImageGrid:57"
     ],
     "Timer": [
       "lib/matplotlib/backend_bases.py:docstring of matplotlib.backend_bases.FigureCanvasBase.new_timer:2",

lib/matplotlib/artist.py

@@ -10,7 +10,7 @@
 import numpy as np
 
 import matplotlib as mpl
-from . import _api, cbook, docstring
+from . import _api, cbook
 from .path import Path
 from .transforms import (Bbox, IdentityTransform, Transform, TransformedBbox,
                          TransformedPatchPath, TransformedPath)
@@ -1697,6 +1697,3 @@ def kwdoc(artist):
     return ('\n'.join(ai.pprint_setters_rest(leadingspace=4))
             if mpl.rcParams['docstring.hardcopy'] else
             'Properties:\n' + '\n'.join(ai.pprint_setters(leadingspace=4)))
-
-
-docstring.interpd.update(Artist_kwdoc=kwdoc(Artist))

lib/matplotlib/axes/_axes.py

@@ -43,6 +43,7 @@
 # All the other methods should go in the _AxesBase class.
 
 
+@docstring.interpd
 class Axes(_AxesBase):
     """
     The `Axes` contains most of the figure elements: `~.axis.Axis`,
@@ -397,7 +398,7 @@ def indicate_inset(self, bounds, inset_ax=None, *, transform=None,
         **kwargs
             Other keyword arguments are passed on to the `.Rectangle` patch:
 
-            %(Rectangle_kwdoc)s
+            %(Rectangle:kwdoc)s
 
         Returns
         -------
@@ -609,7 +610,7 @@ def text(self, x, y, s, fontdict=None, **kwargs):
         **kwargs : `~matplotlib.text.Text` properties.
             Other miscellaneous text parameters.
 
-            %(Text_kwdoc)s
+            %(Text:kwdoc)s
 
         Examples
         --------
@@ -686,7 +687,7 @@ def axhline(self, y=0, xmin=0, xmax=1, **kwargs):
             Valid keyword arguments are `.Line2D` properties, with the
             exception of 'transform':
 
-            %(Line2D_kwdoc)s
+            %(Line2D:kwdoc)s
 
         See Also
         --------
@@ -753,7 +754,7 @@ def axvline(self, x=0, ymin=0, ymax=1, **kwargs):
             Valid keyword arguments are `.Line2D` properties, with the
             exception of 'transform':
 
-            %(Line2D_kwdoc)s
+            %(Line2D:kwdoc)s
 
         See Also
         --------
@@ -837,7 +838,7 @@ def axline(self, xy1, xy2=None, *, slope=None, **kwargs):
         **kwargs
             Valid kwargs are `.Line2D` properties
 
-            %(Line2D_kwdoc)s
+            %(Line2D:kwdoc)s
 
         See Also
         --------
@@ -905,7 +906,7 @@ def axhspan(self, ymin, ymax, xmin=0, xmax=1, **kwargs):
         ----------------
         **kwargs : `~matplotlib.patches.Polygon` properties
 
-        %(Polygon_kwdoc)s
+        %(Polygon:kwdoc)s
 
         See Also
         --------
@@ -953,7 +954,7 @@ def axvspan(self, xmin, xmax, ymin=0, ymax=1, **kwargs):
         ----------------
         **kwargs : `~matplotlib.patches.Polygon` properties
 
-        %(Polygon_kwdoc)s
+        %(Polygon:kwdoc)s
 
         See Also
         --------
@@ -1506,7 +1507,7 @@ def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs):
 
             Here is a list of available `.Line2D` properties:
 
-            %(Line2D_kwdoc)s
+            %(Line2D:kwdoc)s
 
         See Also
         --------
@@ -1663,7 +1664,7 @@ def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False,
         **kwargs
             Keyword arguments control the `.Line2D` properties:
 
-            %(Line2D_kwdoc)s
+            %(Line2D:kwdoc)s
 
         See Also
         --------
@@ -2234,7 +2235,7 @@ def bar(self, x, height, width=0.8, bottom=None, *, align="center",
 
         **kwargs : `.Rectangle` properties
 
-        %(Rectangle_kwdoc)s
+        %(Rectangle:kwdoc)s
 
         See Also
         --------
@@ -2509,7 +2510,7 @@ def barh(self, y, width, height=0.8, left=None, *, align="center",
 
         **kwargs : `.Rectangle` properties
 
-        %(Rectangle_kwdoc)s
+        %(Rectangle:kwdoc)s
 
         See Also
         --------
@@ -2697,7 +2698,7 @@ def broken_barh(self, xranges, yrange, **kwargs):
 
             Supported keywords:
 
-            %(BrokenBarHCollection_kwdoc)s
+            %(BrokenBarHCollection:kwdoc)s
         """
         # process the unit information
         if len(xranges):
@@ -3288,7 +3289,7 @@ def errorbar(self, x, y, yerr=None, xerr=None,
 
             Valid kwargs for the marker properties are `.Line2D` properties:
 
-            %(Line2D_kwdoc)s
+            %(Line2D:kwdoc)s
         """
         kwargs = cbook.normalize_kwargs(kwargs, mlines.Line2D)
         # anything that comes in as 'None', drop so the default thing
@@ -4690,7 +4691,7 @@ def reduce_C_function(C: array) -> float
         **kwargs : `~matplotlib.collections.PolyCollection` properties
             All other keyword arguments are passed on to `.PolyCollection`:
 
-            %(PolyCollection_kwdoc)s
+            %(PolyCollection:kwdoc)s
 
         """
         self._process_unit_info([("x", x), ("y", y)], kwargs, convert=False)
@@ -5199,7 +5200,7 @@ def _fill_between_x_or_y(
             All other keyword arguments are passed on to `.PolyCollection`.
             They control the `.Polygon` properties:
 
-            %(PolyCollection_kwdoc)s
+            %(PolyCollection:kwdoc)s
 
         See Also
         --------
@@ -5806,7 +5807,7 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
             Additionally, the following arguments are allowed. They are passed
             along to the `~matplotlib.collections.PolyCollection` constructor:
 
-        %(PolyCollection_kwdoc)s
+        %(PolyCollection:kwdoc)s
 
         See Also
         --------
@@ -6051,7 +6052,7 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
             Additionally, the following arguments are allowed. They are passed
             along to the `~matplotlib.collections.QuadMesh` constructor:
 
-        %(QuadMesh_kwdoc)s
+        %(QuadMesh:kwdoc)s
 
         See Also
         --------
@@ -7091,7 +7092,7 @@ def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
         **kwargs
             Keyword arguments control the `.Line2D` properties:
 
-            %(Line2D_kwdoc)s
+            %(Line2D:kwdoc)s
 
         See Also
         --------
@@ -7204,7 +7205,7 @@ def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
         **kwargs
             Keyword arguments control the `.Line2D` properties:
 
-            %(Line2D_kwdoc)s
+            %(Line2D:kwdoc)s
 
         See Also
         --------
@@ -7294,7 +7295,7 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
         **kwargs
             Keyword arguments control the `.Line2D` properties:
 
-            %(Line2D_kwdoc)s
+            %(Line2D:kwdoc)s
 
         See Also
         --------
@@ -7371,7 +7372,7 @@ def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
         **kwargs
             Keyword arguments control the `.Line2D` properties:
 
-            %(Line2D_kwdoc)s
+            %(Line2D:kwdoc)s
 
         See Also
         --------
@@ -7437,7 +7438,7 @@ def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
         **kwargs
             Keyword arguments control the `.Line2D` properties:
 
-            %(Line2D_kwdoc)s
+            %(Line2D:kwdoc)s
 
         See Also
         --------
@@ -7504,7 +7505,7 @@ def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
         **kwargs
             Keyword arguments control the `.Line2D` properties:
 
-            %(Line2D_kwdoc)s
+            %(Line2D:kwdoc)s
 
         References
         ----------
@@ -7754,7 +7755,7 @@ def spy(self, Z, precision=0, marker=None, markersize=None,
             For the marker style, you can pass any `.Line2D` property except
             for *linestyle*:
 
-            %(Line2D_kwdoc)s
+            %(Line2D:kwdoc)s
         """
         if marker is None and markersize is None and hasattr(Z, 'tocoo'):
             marker = 's'

lib/matplotlib/axes/_base.py

@@ -586,7 +586,7 @@ def __init__(self, fig, rect,
         **kwargs
             Other optional keyword arguments:
 
-            %(Axes_kwdoc)s
+            %(Axes:kwdoc)s
 
         Returns
         -------
@@ -3219,7 +3219,7 @@ def grid(self, visible=None, which='major', axis='both', **kwargs):
 
             Valid keyword arguments are:
 
-            %(Line2D_kwdoc)s
+            %(Line2D:kwdoc)s
 
         Notes
         -----