8000 Auto-generate required kwdoc entries into docstring.interpd. by anntzer · Pull Request #20164 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

Auto-generate required kwdoc entries into docstring.interpd. #20164

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 24, 2021
Merged

Auto-generate required kwdoc entries into docstring.interpd. #20164

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2bb1343
Auto-generate required kwdoc entries into docstring.interpd.
anntzer Jan 18, 2021
a0b7d83
Update missing-references.
anntzer May 5, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 15 additions & 25 deletions doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
41 changes: 26 additions & 15 deletions doc/missing-references.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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"
],
Expand All @@ -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"
]
Expand Down Expand Up @@ -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"
],
Expand Down Expand Up @@ -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",
Expand Down
5 changes: 1 addition & 4 deletions lib/matplotlib/artist.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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))
49 changes: 25 additions & 24 deletions lib/matplotlib/axes/_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand Down Expand Up @@ -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
-------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
558 %(Line2D:kwdoc)s

S 10670 ee Also
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
--------
Expand Down Expand Up @@ -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
----------
Expand Down Expand Up @@ -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'
Expand Down
4 changes: 2 additions & 2 deletions lib/matplotlib/axes/_base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -586,7 +586,7 @@ def __init__(self, fig, rect,
**kwargs
Other optional keyword arguments:

%(Axes_kwdoc)s
%(Axes:kwdoc)s

Returns
-------
Expand Down Expand Up @@ -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
-----
Expand Down
Loading
0