diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 3cb4f5f1cc23..9ef42ab4d356 100644 --- a/doc/devel/documenting_mpl.rst +++ b/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 diff --git a/doc/missing-references.json b/doc/missing-references.json index 8e0580848c19..5a5d6237a549 100644 --- a/doc/missing-references.json +++ b/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", diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py index b4d37c261b26..65225adcdc50 100644 --- a/lib/matplotlib/artist.py +++ b/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)) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 58994cc8c456..7750cf186384 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/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 @@ -4740,7 +4741,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) @@ -5249,7 +5250,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 -------- @@ -5847,7 +5848,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 -------- @@ -6092,7 +6093,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 -------- @@ -7133,7 +7134,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 -------- @@ -7246,7 +7247,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 -------- @@ -7336,7 +7337,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 -------- @@ -7413,7 +7414,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 -------- @@ -7479,7 +7480,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 -------- @@ -7546,7 +7547,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 ---------- @@ -7796,7 +7797,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' diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index f72e2950100f..6bafce70d9c6 100644 --- a/lib/matplotlib/axes/_base.py +++ b/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 ------- @@ -3217,7 +3217,7 @@ def grid(self, b=None, which='major', axis='both', **kwargs): Valid keyword arguments are: - %(Line2D_kwdoc)s + %(Line2D:kwdoc)s Notes ----- diff --git a/lib/matplotlib/axes/_subplots.py b/lib/matplotlib/axes/_subplots.py index ca5a40d2c39e..5e8d3822fa53 100644 --- a/lib/matplotlib/axes/_subplots.py +++ b/lib/matplotlib/axes/_subplots.py @@ -1,7 +1,6 @@ import functools -from matplotlib import _api, docstring -import matplotlib.artist as martist +from matplotlib import _api from matplotlib.axes._axes import Axes from matplotlib.gridspec import GridSpec, SubplotSpec @@ -220,9 +219,3 @@ class when called with an axes class. This is purely to allow pickling of """ subplot_class = subplot_class_factory(axes_class) return subplot_class.__new__(subplot_class) - - -docstring.interpd.update(Axes_kwdoc=martist.kwdoc(Axes)) -docstring.dedent_interpd(Axes.__init__) - -docstring.interpd.update(Subplot_kwdoc=martist.kwdoc(Axes)) diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py index 002f3fc8d5ab..ba96004f3d71 100644 --- a/lib/matplotlib/collections.py +++ b/lib/matplotlib/collections.py @@ -2097,12 +2097,3 @@ def draw(self, renderer): gc.restore() renderer.close_group(self.__class__.__name__) self.stale = False - - -_artist_kwdoc = artist.kwdoc(Collection) -for k in ('QuadMesh', 'TriMesh', 'PolyCollection', 'BrokenBarHCollection', - 'RegularPolyCollection', 'PathCollection', - 'StarPolygonCollection', 'PatchCollection', - 'CircleCollection', 'Collection',): - docstring.interpd.update({f'{k}_kwdoc': _artist_kwdoc}) -docstring.interpd.update(LineCollection_kwdoc=artist.kwdoc(LineCollection)) diff --git a/lib/matplotlib/docstring.py b/lib/matplotlib/docstring.py index d0e661ffffd9..2ae79c9b2f36 100644 --- a/lib/matplotlib/docstring.py +++ b/lib/matplotlib/docstring.py @@ -33,7 +33,7 @@ def some_function(x): def __init__(self, *args, **kwargs): if args and kwargs: raise TypeError("Only positional or keyword args are allowed") - self.params = args or kwargs + self.params = params = args or kwargs def __call__(self, func): if func.__doc__: @@ -62,6 +62,48 @@ def from_params(cls, params): return result +def _recursive_subclasses(cls): + yield cls + for subcls in cls.__subclasses__(): + yield from _recursive_subclasses(subcls) + + +class _ArtistKwdocLoader(dict): + def __missing__(self, key): + if not key.endswith(":kwdoc"): + raise KeyError(key) + name = key[:-len(":kwdoc")] + from matplotlib.artist import Artist, kwdoc + try: + cls, = [cls for cls in _recursive_subclasses(Artist) + if cls.__name__ == name] + except ValueError as e: + raise KeyError(key) from e + return self.setdefault(key, kwdoc(cls)) + + +class _ArtistPropertiesSubstitution(Substitution): + """ + A `.Substitution` with two additional features: + + - Substitutions of the form ``%(classname:kwdoc)s`` (ending with the + literal ":kwdoc" suffix) trigger lookup of an Artist subclass with the + given *classname*, and are substituted with the `.kwdoc` of that class. + - Decorating a class triggers substitution both on the class docstring and + on the class' ``__init__`` docstring (which is a commonly required + pattern for Artist subclasses). + """ + + def __init__(self): + self.params = _ArtistKwdocLoader() + + def __call__(self, obj): + super().__call__(obj) + if isinstance(obj, type) and obj.__init__ != object.__init__: + self(obj.__init__) + return obj + + def copy(source): """Copy a docstring from another source function (if present).""" def do_copy(target): @@ -73,5 +115,4 @@ def do_copy(target): # Create a decorator that will house the various docstring snippets reused # throughout Matplotlib. -interpd = Substitution() -dedent_interpd = interpd +dedent_interpd = interpd = _ArtistPropertiesSubstitution() diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 3e03f7a7f198..85e240a9e47c 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -23,7 +23,6 @@ import matplotlib as mpl from matplotlib import docstring, projections -import matplotlib.artist as martist from matplotlib.artist import ( Artist, allow_rasterization, _finalize_rasterization) from matplotlib.backend_bases import ( @@ -593,7 +592,7 @@ def add_axes(self, *args, **kwargs): arguments if another projection is used, see the actual Axes class. - %(Axes_kwdoc)s + %(Axes:kwdoc)s Notes ----- @@ -731,7 +730,7 @@ def add_subplot(self, *args, **kwargs): the following table but there might also be other keyword arguments if another projection is used. - %(Axes_kwdoc)s + %(Axes:kwdoc)s See Also -------- @@ -1101,7 +1100,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 See Also -------- @@ -1484,8 +1483,7 @@ def gca(self, **kwargs): adheres to the given projection etc., and for Axes creation if the active Axes does not exist: - %(Axes_kwdoc)s - + %(Axes:kwdoc)s """ if kwargs: _api.warn_deprecated( @@ -3181,6 +3179,3 @@ def figaspect(arg): # the min/max dimensions (we don't want figures 10 feet tall!) newsize = np.clip(newsize, figsize_min, figsize_max) return newsize - - -docstring.interpd.update(Figure_kwdoc=martist.kwdoc(Figure)) diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py index 8d1fd6b037b7..3f46a1e1e484 100644 --- a/lib/matplotlib/lines.py +++ b/lib/matplotlib/lines.py @@ -195,6 +195,7 @@ def _slice_or_none(in_v, slc): raise ValueError(f"markevery={markevery!r} is not a recognized value") +@docstring.interpd @cbook._define_aliases({ "antialiased": ["aa"], "color": ["c"], @@ -299,7 +300,7 @@ def __init__(self, xdata, ydata, Additional keyword arguments are `.Line2D` properties: - %(Line2D_kwdoc)s + %(Line2D:kwdoc)s See :meth:`set_linestyle` for a description of the line styles, :meth:`set_marker` for a description of the markers, and @@ -1524,6 +1525,3 @@ def onpick(self, event): lineMarkers = MarkerStyle.markers drawStyles = Line2D.drawStyles fillStyles = MarkerStyle.fillstyles - -docstring.interpd.update(Line2D_kwdoc=artist.kwdoc(Line2D)) -docstring.interpd(Line2D.__init__) diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py index b19e8480c707..9017972fee5d 100644 --- a/lib/matplotlib/patches.py +++ b/lib/matplotlib/patches.py @@ -23,6 +23,7 @@ from ._enums import JoinStyle, CapStyle +@docstring.interpd @cbook._define_aliases({ "antialiased": ["aa"], "edgecolor": ["ec"], @@ -70,7 +71,7 @@ def __init__(self, """ The following kwarg properties are supported - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ super().__init__() @@ -631,16 +632,6 @@ def _convert_xy_units(self, xy): return x, y -_patch_kwdoc = artist.kwdoc(Patch) -for k in ['Rectangle', 'Circle', 'RegularPolygon', 'Polygon', 'Wedge', 'Arrow', - 'FancyArrow', 'CirclePolygon', 'Ellipse', 'Arc', 'FancyBboxPatch', - 'Patch']: - docstring.interpd.update({f'{k}_kwdoc': _patch_kwdoc}) - -# define Patch.__init__ docstring after the class has been added to interpd -docstring.dedent_interpd(Patch.__init__) - - class Shadow(Patch): def __str__(self): return "Shadow(%s)" % (str(self.patch)) @@ -666,7 +657,7 @@ def __init__(self, patch, ox, oy, props=None, **kwargs): **kwargs Properties of the shadow patch. Supported keys are: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ super().__init__() self.patch = patch @@ -751,7 +742,7 @@ def __init__(self, xy, width, height, angle=0.0, **kwargs): Other Parameters ---------------- **kwargs : `.Patch` properties - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ super().__init__(**kwargs) self._x0 = xy[0] @@ -905,7 +896,7 @@ def __init__(self, xy, numVertices, radius=5, orientation=0, **kwargs `Patch` properties: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ self.xy = xy self.numvertices = numVertices @@ -941,7 +932,7 @@ def __init__(self, path, **kwargs): Valid keyword arguments are: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ super().__init__(**kwargs) self._path = path @@ -988,7 +979,7 @@ def __init__(self, values, edges, *, Other valid keyword arguments are: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ self.orientation = orientation self._edges = np.asarray(edges) @@ -1078,7 +1069,7 @@ def __init__(self, xy, closed=True, **kwargs): Valid keyword arguments are: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ super().__init__(**kwargs) self._closed = closed @@ -1174,7 +1165,7 @@ def __init__(self, center, r, theta1, theta2, width=None, **kwargs): Valid keyword arguments are: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ super().__init__(**kwargs) self.center = center @@ -1282,7 +1273,7 @@ def __init__(self, x, y, dx, dy, width=1.0, **kwargs): **kwargs Keyword arguments control the `Patch` properties: - %(Patch_kwdoc)s + %(Patch:kwdoc)s See Also -------- @@ -1354,7 +1345,7 @@ def __init__(self, x, y, dx, dy, width=0.001, length_includes_head=False, **kwargs `.Patch` properties: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ self._x = x self._y = y @@ -1496,7 +1487,7 @@ def __init__(self, xy, radius=5, Valid keyword arguments are: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ super().__init__(xy, resolution, radius, orientation=0, **kwargs) @@ -1528,7 +1519,7 @@ def __init__(self, xy, width, height, angle=0, **kwargs): ----- Valid keyword arguments are: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ super().__init__(**kwargs) @@ -1664,7 +1655,7 @@ def __init__(self, xy, r, width, angle=0.0, **kwargs): **kwargs Keyword arguments control the `Patch` properties: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ super().__init__(**kwargs) @@ -1842,7 +1833,7 @@ def __init__(self, xy, radius=5, **kwargs): Valid keyword arguments are: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ super().__init__(xy, radius * 2, radius * 2, **kwargs) self.radius = radius @@ -1919,7 +1910,7 @@ def __init__(self, xy, width, height, angle=0.0, with the exception of *fill* and *facecolor* because filling is not supported. - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ fill = kwargs.setdefault('fill', False) if fill: @@ -3838,7 +3829,7 @@ def __init__(self, xy, width, height, ---------------- **kwargs : `.Patch` properties - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ super().__init__(**kwargs) @@ -4158,7 +4149,7 @@ def __init__(self, posA=None, posB=None, path=None, **kwargs : `.Patch` properties, optional Here is a list of available `.Patch` properties: - %(Patch_kwdoc)s + %(Patch:kwdoc)s In contrast to other patches, the default ``capstyle`` and ``joinstyle`` for `FancyArrowPatch` are set to ``"round"``. diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index fcee92477870..4839976c3a42 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -1023,7 +1023,7 @@ def axes(arg=None, **kwargs): arguments if another projection is used, see the actual axes class. - %(Axes_kwdoc)s + %(Axes:kwdoc)s Notes ----- @@ -1155,7 +1155,7 @@ def subplot(*args, **kwargs): the following table but there might also be other keyword arguments if another projection is used. - %(Axes_kwdoc)s + %(Axes:kwdoc)s Notes ----- diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py index 6d6fe01338c4..e595b67f1b9b 100644 --- a/lib/matplotlib/quiver.py +++ b/lib/matplotlib/quiver.py @@ -184,7 +184,7 @@ **kwargs : `~matplotlib.collections.PolyCollection` properties, optional All other keyword arguments are passed on to `.PolyCollection`: - %(PolyCollection_kwdoc)s + %(PolyCollection:kwdoc)s Returns ------- @@ -892,7 +892,7 @@ def _h_arrows(self, length): The barbs can further be customized using `.PolyCollection` keyword arguments: - %(PolyCollection_kwdoc)s + %(PolyCollection:kwdoc)s """ % docstring.interpd.params docstring.interpd.update(barbs_doc=_barbs_doc) diff --git a/lib/matplotlib/sankey.py b/lib/matplotlib/sankey.py index 8032001561bb..196df813a3a4 100644 --- a/lib/matplotlib/sankey.py +++ b/lib/matplotlib/sankey.py @@ -431,7 +431,7 @@ def add(self, patchlabel='', flows=None, orientations=None, labels='', properties, listed below. For example, one may want to use ``fill=False`` or ``label="A legend entry"``. - %(Patch_kwdoc)s + %(Patch:kwdoc)s See Also -------- diff --git a/lib/matplotlib/spines.py b/lib/matplotlib/spines.py index 40ceb157fd6e..b07514d324d8 100644 --- a/lib/matplotlib/spines.py +++ b/lib/matplotlib/spines.py @@ -48,7 +48,7 @@ def __init__(self, axes, spine_type, path, **kwargs): **kwargs Valid keyword arguments are: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ super().__init__(**kwargs) self.axes = axes diff --git a/lib/matplotlib/table.py b/lib/matplotlib/table.py index 965cb6eeda9b..43b7c255c9a0 100644 --- a/lib/matplotlib/table.py +++ b/lib/matplotlib/table.py @@ -19,7 +19,7 @@ Thanks to John Gill for providing the class and table. """ -from . import _api, artist, docstring +from . import _api, docstring from .artist import Artist, allow_rasterization from .patches import Rectangle from .text import Text @@ -177,7 +177,7 @@ def set_text_props(self, **kwargs): Valid keyword arguments are: - %(Text_kwdoc)s + %(Text:kwdoc)s """ self._text.update(kwargs) self.stale = True @@ -639,9 +639,6 @@ def get_celld(self): return self._cells -docstring.interpd.update(Table_kwdoc=artist.kwdoc(Table)) - - @docstring.dedent_interpd def table(ax, cellText=None, cellColours=None, @@ -723,7 +720,7 @@ def table(ax, **kwargs `.Table` properties. - %(Table_kwdoc)s + %(Table:kwdoc)s """ if cellColours is None and cellText is None: diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py index 072a07f503d3..5ea269005ac8 100644 --- a/lib/matplotlib/text.py +++ b/lib/matplotlib/text.py @@ -103,6 +103,7 @@ def _get_textbox(text, renderer): return x_box, y_box, w_box, h_box +@docstring.interpd @cbook._define_aliases({ "color": ["c"], "fontfamily": ["family"], @@ -146,7 +147,7 @@ def __init__(self, Valid keyword arguments are: - %(Text_kwdoc)s + %(Text:kwdoc)s """ super().__init__() self._x, self._y = x, y @@ -1306,10 +1307,6 @@ def set_fontname(self, fontname): return self.set_family(fontname) -docstring.interpd.update(Text_kwdoc=artist.kwdoc(Text)) -docstring.dedent_interpd(Text.__init__) - - class OffsetFrom: """Callable helper class for working with `Annotation`.""" diff --git a/lib/mpl_toolkits/axes_grid1/inset_locator.py b/lib/mpl_toolkits/axes_grid1/inset_locator.py index be5c768f4ce0..5193cc540c31 100644 --- a/lib/mpl_toolkits/axes_grid1/inset_locator.py +++ b/lib/mpl_toolkits/axes_grid1/inset_locator.py @@ -148,7 +148,7 @@ def __init__(self, bbox, **kwargs): **kwargs Patch properties. Valid arguments include: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ if "transform" in kwargs: raise ValueError("transform should not be set") @@ -270,7 +270,7 @@ def __init__(self, bbox1, bbox2, loc1, loc2=None, **kwargs): **kwargs Patch properties for the line drawn. Valid arguments include: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ if "transform" in kwargs: raise ValueError("transform should not be set") @@ -329,7 +329,7 @@ def __init__(self, bbox1, bbox2, loc1a, loc2a, loc1b, loc2b, **kwargs): **kwargs Patch properties for the line drawn: - %(Patch_kwdoc)s + %(Patch:kwdoc)s """ if "transform" in kwargs: raise ValueError("transform should not be set") @@ -441,7 +441,7 @@ def inset_axes(parent_axes, width, height, loc='upper right', Keyword arguments to pass to the constructor of the inset axes. Valid arguments include: - %(Axes_kwdoc)s + %(Axes:kwdoc)s borderpad : float, default: 0.5 Padding between inset axes and the bbox_to_anchor. @@ -548,7 +548,7 @@ def zoomed_inset_axes(parent_axes, zoom, loc='upper right', Keyword arguments to pass to the constructor of the inset axes. Valid arguments include: - %(Axes_kwdoc)s + %(Axes:kwdoc)s borderpad : float, default: 0.5 Padding between inset axes and the bbox_to_anchor. @@ -603,7 +603,7 @@ def mark_inset(parent_axes, inset_axes, loc1, loc2, **kwargs): **kwargs Patch properties for the lines and box drawn: - %(Patch_kwdoc)s + %(Patch:kwdoc)s Returns ------- diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py index ed97b9658560..47446560ad70 100644 --- a/lib/mpl_toolkits/mplot3d/axes3d.py +++ b/lib/mpl_toolkits/mplot3d/axes3d.py @@ -40,6 +40,7 @@ from . import axis3d +@docstring.interpd @cbook._define_aliases({ "xlim3d": ["xlim"], "ylim3d": ["ylim"], "zlim3d": ["zlim"]}) class Axes3D(Axes): @@ -90,7 +91,7 @@ def __init__( **kwargs Other optional keyword arguments: - %(Axes3D_kwdoc)s + %(Axes3D:kwdoc)s """ if rect is None: @@ -3443,10 +3444,6 @@ def stem(self, x, y, z, *, linefmt='C0-', markerfmt='C0o', basefmt='C3-', stem3D = stem -docstring.interpd.update(Axes3D_kwdoc=martist.kwdoc(Axes3D)) -docstring.dedent_interpd(Axes3D.__init__) - - def get_test_data(delta=0.05): """Return a tuple X, Y, Z with a test data set.""" x = y = np.arange(-3.0, 3.0, delta)