Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit ca6e9dc

Browse files
jklymakjklymak
authored
Merge pull request #20164 from anntzer/autokwdoc
Auto-generate required kwdoc entries into docstring.interpd.
2 parents 8ecc571 + a0b7d83 commit ca6e9dc

19 files changed

Lines changed: 157 additions & 158 deletions

‎doc/devel/documenting_mpl.rst‎

Lines changed: 15 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -658,26 +658,14 @@ are:
658658
2. as automated as possible so that as properties change, the docs
659659
are updated automatically.
660660

661-
The function `matplotlib.artist.kwdoc` and the decorator
662-
``matplotlib.docstring.dedent_interpd`` facilitate this. They combine Python
663-
string interpolation in the docstring with the Matplotlib artist introspection
664-
facility that underlies ``setp`` and ``getp``. The ``kwdoc`` function gives
665-
the list of properties as a docstring. In order to use this in another
666-
docstring, first update the ``matplotlib.docstring.interpd`` object, as seen in
667-
this example from `matplotlib.lines`:
668-
669-
.. code-block:: python
670-
671-
# in lines.py
672-
docstring.interpd.update(Line2D_kwdoc=artist.kwdoc(Line2D))
673-
674-
Then in any function accepting `~.Line2D` pass-through ``kwargs``, e.g.,
675-
`matplotlib.axes.Axes.plot`:
661+
The ``@docstring.interpd`` decorator implements this. Any function accepting
662+
`.Line2D` pass-through ``kwargs``, e.g., `matplotlib.axes.Axes.plot`, can list
663+
a summary of the `.Line2D` properties, as follows:
676664

677665
.. code-block:: python
678666
679667
# in axes.py
680-
@docstring.dedent_interpd
668+
@docstring.interpd
681669
def plot(self, *args, **kwargs):
682670
"""
683671
Some stuff omitted
@@ -702,17 +690,19 @@ Then in any function accepting `~.Line2D` pass-through ``kwargs``, e.g.,
702690
703691
Here is a list of available `.Line2D` properties:
704692
705-
%(Line2D_kwdoc)s
706-
693+
%(Line2D:kwdoc)s
707694
"""
708695
709-
Note there is a problem for `~matplotlib.artist.Artist` ``__init__`` methods,
710-
e.g., `matplotlib.patches.Patch`, which supports ``Patch`` ``kwargs``,
711-
since the artist inspector cannot work until the class is fully defined and
712-
we can't modify the ``Patch.__init__.__doc__`` docstring outside the class
713-
definition. There are some some manual hacks in this case, violating the
714-
"single entry point" requirement above -- see the ``docstring.interpd.update``
715-
calls in `matplotlib.patches`.
696+
The ``%(Line2D:kwdoc)`` syntax makes ``interpd`` lookup an `.Artist` subclass
697+
named ``Line2D``, and call `.artist.kwdoc` on that class. `.artist.kwdoc`
698+
introspects the subclass and summarizes its properties as a substring, which
699+
gets interpolated into the docstring.
700+
701+
Note that this scheme does not work for decorating an Artist's ``__init__``, as
702+
the subclass and its properties are not defined yet at that point. Instead,
703+
``@docstring.interpd`` can be used to decorate the class itself -- at that
704+
point, `.kwdoc` can list the properties and interpolate them into
705+
``__init__.__doc__``.
716706

717707

718708
Inheriting docstrings

‎doc/missing-references.json‎

Lines changed: 26 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -14,16 +14,15 @@
1414
"lib/matplotlib/ticker.py:docstring of matplotlib.ticker.LogitLocator.tick_values:5",
1515
"lib/matplotlib/ticker.py:docstring of matplotlib.ticker.MaxNLocator.tick_values:5",
1616
"lib/matplotlib/ticker.py:docstring of matplotlib.ticker.MultipleLocator.tick_values:5",
17-
"lib/matplotlib/ticker.py:docstring of matplotlib.ticker.OldAutoLocator.tick_values:5",
1817
"lib/matplotlib/ticker.py:docstring of matplotlib.ticker.SymmetricalLogLocator.tick_values:5"
1918
],
2019
"button": [
2120
"doc/users/prev_whats_new/whats_new_3.1.0.rst:335"
2221
],
2322
"cbar_axes": [
24-
"lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid.__init__:49",
25-
"lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid:49",
26-
"lib/mpl_toolkits/axisartist/axes_grid.py:docstring of mpl_toolkits.axisartist.axes_grid.ImageGrid:49"
23+
"lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid.__init__:45",
24+
"lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid:45",
25+
"lib/mpl_toolkits/axisartist/axes_grid.py:docstring of mpl_toolkits.axisartist.axes_grid.ImageGrid:45"
2726
],
2827
"eventson": [
2928
"lib/matplotlib/widgets.py:docstring of matplotlib.widgets.CheckButtons.set_active:4",
@@ -574,6 +573,26 @@
574573
"get_matrix": [
575574
"lib/matplotlib/transforms.py:docstring of matplotlib.transforms.Affine2DBase:13"
576575
],
576+
"matplotlib.collections._CollectionWithSizes.set_sizes": [
577+
"lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.barbs:172",
578+
"lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.broken_barh:82",
579+
"lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.fill_between:112",
580+
"lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.fill_betweenx:112",
581+
"lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.hexbin:168",
582+
"lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.pcolor:165",
583+
"lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.quiver:202",
584+
"lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.barbs:172",
585+
"lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.broken_barh:82",
586+
"lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.fill_between:112",
587+
"lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.fill_betweenx:112",
588+
"lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.hexbin:168",
589+
"lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.pcolor:165",
590+
"lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.quiver:202",
591+
"lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Barbs.__init__:176",
592+
"lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Barbs:206",
593+
"lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Quiver.__init__:206",
594+
"lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Quiver:239"
595+
],
577596
"matplotlib.dates.DateFormatter.__call__": [
578597
"doc/users/prev_whats_new/whats_new_1.5.rst:497"
579598
],
@@ -594,11 +613,6 @@
594613
"dateutil": [
595614
"lib/matplotlib/dates.py:docstring of matplotlib.dates:1"
596615
],
597-
"matplotlib": [
598-
"doc/api/next_api_changes/deprecations/19517-AL.rst:3",
599-
"doc/api/prev_api_changes/api_changes_0.91.2.rst:15",
600-
"doc/api/prev_api_changes/api_changes_3.4.0/deprecations.rst:58"
601-
],
602616
"matplotlib.ft2font": [
603617
"doc/api/prev_api_changes/api_changes_0.91.0.rst:34"
604618
]
@@ -669,9 +683,6 @@
669683
"lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.violinplot:46",
670684
"lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.violinplot:46"
671685
],
672-
"Glue": [
673-
"lib/matplotlib/mathtext.py:docstring of matplotlib.mathtext.GlueSpec:2"
674-
],
675686
"Glyph": [
676687
"doc/gallery/misc/ftface_props.rst:25"
677688
],
@@ -716,9 +727,9 @@
716727
"doc/users/event_handling.rst:179"
717728
],
718729
"Size.from_any": [
719-
"lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid.__init__:61",
720-
"lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid:61",
721-
"lib/mpl_toolkits/axisartist/axes_grid.py:docstring of mpl_toolkits.axisartist.axes_grid.ImageGrid:61"
730+
"lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid.__init__:57",
731+
"lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid:57",
732+
"lib/mpl_toolkits/axisartist/axes_grid.py:docstring of mpl_toolkits.axisartist.axes_grid.ImageGrid:57"
722733
],
723734
"Timer": [
724735
"lib/matplotlib/backend_bases.py:docstring of matplotlib.backend_bases.FigureCanvasBase.new_timer:2",

‎lib/matplotlib/artist.py‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
import numpy as np
1111

1212
import matplotlib as mpl
13-
from . import _api, cbook, docstring
13+
from . import _api, cbook
1414
from .path import Path
1515
from .transforms import (Bbox, IdentityTransform, Transform, TransformedBbox,
1616
TransformedPatchPath, TransformedPath)
@@ -1697,6 +1697,3 @@ def kwdoc(artist):
16971697
return ('\n'.join(ai.pprint_setters_rest(leadingspace=4))
16981698
if mpl.rcParams['docstring.hardcopy'] else
16991699
'Properties:\n' + '\n'.join(ai.pprint_setters(leadingspace=4)))
1700-
1701-
1702-
docstring.interpd.update(Artist_kwdoc=kwdoc(Artist))

‎lib/matplotlib/axes/_axes.py‎

Lines changed: 25 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@
4343
# All the other methods should go in the _AxesBase class.
4444

4545

46+
@docstring.interpd
4647
class Axes(_AxesBase):
4748
"""
4849
The `Axes` contains most of the figure elements: `~.axis.Axis`,
@@ -397,7 +398,7 @@ def indicate_inset(self, bounds, inset_ax=None, *, transform=None,
397398
**kwargs
398399
Other keyword arguments are passed on to the `.Rectangle` patch:
399400
400-
%(Rectangle_kwdoc)s
401+
%(Rectangle:kwdoc)s
401402
402403
Returns
403404
-------
@@ -609,7 +610,7 @@ def text(self, x, y, s, fontdict=None, **kwargs):
609610
**kwargs : `~matplotlib.text.Text` properties.
610611
Other miscellaneous text parameters.
611612
612-
%(Text_kwdoc)s
613+
%(Text:kwdoc)s
613614
614615
Examples
615616
--------
@@ -686,7 +687,7 @@ def axhline(self, y=0, xmin=0, xmax=1, **kwargs):
686687
Valid keyword arguments are `.Line2D` properties, with the
687688
exception of 'transform':
688689
689-
%(Line2D_kwdoc)s
690+
%(Line2D:kwdoc)s
690691
691692
See Also
692693
--------
@@ -753,7 +754,7 @@ def axvline(self, x=0, ymin=0, ymax=1, **kwargs):
753754
Valid keyword arguments are `.Line2D` properties, with the
754755
exception of 'transform':
755756
756-
%(Line2D_kwdoc)s
757+
%(Line2D:kwdoc)s
757758
758759
See Also
759760
--------
@@ -837,7 +838,7 @@ def axline(self, xy1, xy2=None, *, slope=None, **kwargs):
837838
**kwargs
838839
Valid kwargs are `.Line2D` properties
839840
840-
%(Line2D_kwdoc)s
841+
%(Line2D:kwdoc)s
841842
842843
See Also
843844
--------
@@ -905,7 +906,7 @@ def axhspan(self, ymin, ymax, xmin=0, xmax=1, **kwargs):
905906
----------------
906907
**kwargs : `~matplotlib.patches.Polygon` properties
907908
908-
%(Polygon_kwdoc)s
909+
%(Polygon:kwdoc)s
909910
910911
See Also
911912
--------
@@ -953,7 +954,7 @@ def axvspan(self, xmin, xmax, ymin=0, ymax=1, **kwargs):
953954
----------------
954955
**kwargs : `~matplotlib.patches.Polygon` properties
955956
956-
%(Polygon_kwdoc)s
957+
%(Polygon:kwdoc)s
957958
958959
See Also
959960
--------
@@ -1506,7 +1507,7 @@ def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs):
15061507
15071508
Here is a list of available `.Line2D` properties:
15081509
1509-
%(Line2D_kwdoc)s
1510+
%(Line2D:kwdoc)s
15101511
15111512
See Also
15121513
--------
@@ -1663,7 +1664,7 @@ def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False,
16631664
**kwargs
16641665
Keyword arguments control the `.Line2D` properties:
16651666
1666-
%(Line2D_kwdoc)s
1667+
%(Line2D:kwdoc)s
16671668
16681669
See Also
16691670
--------
@@ -2234,7 +2235,7 @@ def bar(self, x, height, width=0.8, bottom=None, *, align="center",
22342235
22352236
**kwargs : `.Rectangle` properties
22362237
2237-
%(Rectangle_kwdoc)s
2238+
%(Rectangle:kwdoc)s
22382239
22392240
See Also
22402241
--------
@@ -2509,7 +2510,7 @@ def barh(self, y, width, height=0.8, left=None, *, align="center",
25092510
25102511
**kwargs : `.Rectangle` properties
25112512
2512-
%(Rectangle_kwdoc)s
2513+
%(Rectangle:kwdoc)s
25132514
25142515
See Also
25152516
--------
@@ -2697,7 +2698,7 @@ def broken_barh(self, xranges, yrange, **kwargs):
26972698
26982699
Supported keywords:
26992700
2700-
%(BrokenBarHCollection_kwdoc)s
2701+
%(BrokenBarHCollection:kwdoc)s
27012702
"""
27022703
# process the unit information
27032704
if len(xranges):
@@ -3288,7 +3289,7 @@ def errorbar(self, x, y, yerr=None, xerr=None,
32883289
32893290
Valid kwargs for the marker properties are `.Line2D` properties:
32903291
3291-
%(Line2D_kwdoc)s
3292+
%(Line2D:kwdoc)s
32923293
"""
32933294
kwargs = cbook.normalize_kwargs(kwargs, mlines.Line2D)
32943295
# anything that comes in as 'None', drop so the default thing
@@ -4690,7 +4691,7 @@ def reduce_C_function(C: array) -> float
46904691
**kwargs : `~matplotlib.collections.PolyCollection` properties
46914692
All other keyword arguments are passed on to `.PolyCollection`:
46924693
4693-
%(PolyCollection_kwdoc)s
4694+
%(PolyCollection:kwdoc)s
46944695
46954696
"""
46964697
self._process_unit_info([("x", x), ("y", y)], kwargs, convert=False)
@@ -5199,7 +5200,7 @@ def _fill_between_x_or_y(
51995200
All other keyword arguments are passed on to `.PolyCollection`.
52005201
They control the `.Polygon` properties:
52015202
5202-
%(PolyCollection_kwdoc)s
5203+
%(PolyCollection:kwdoc)s
52035204
52045205
See Also
52055206
--------
@@ -5806,7 +5807,7 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
58065807
Additionally, the following arguments are allowed. They are passed
58075808
along to the `~matplotlib.collections.PolyCollection` constructor:
58085809
5809-
%(PolyCollection_kwdoc)s
5810+
%(PolyCollection:kwdoc)s
58105811
58115812
See Also
58125813
--------
@@ -6051,7 +6052,7 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
60516052
Additionally, the following arguments are allowed. They are passed
60526053
along to the `~matplotlib.collections.QuadMesh` constructor:
60536054
6054-
%(QuadMesh_kwdoc)s
6055+
%(QuadMesh:kwdoc)s
60556056
60566057
See Also
60576058
--------
@@ -7091,7 +7092,7 @@ def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
70917092
**kwargs
70927093
Keyword arguments control the `.Line2D` properties:
70937094
7094-
%(Line2D_kwdoc)s
7095+
%(Line2D:kwdoc)s
70957096
70967097
See Also
70977098
--------
@@ -7204,7 +7205,7 @@ def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
72047205
**kwargs
72057206
Keyword arguments control the `.Line2D` properties:
72067207
7207-
%(Line2D_kwdoc)s
7208+
%(Line2D:kwdoc)s
72087209
72097210
See Also
72107211
--------
@@ -7294,7 +7295,7 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
72947295
**kwargs
72957296
Keyword arguments control the `.Line2D` properties:
72967297
7297-
%(Line2D_kwdoc)s
7298+
%(Line2D:kwdoc)s
72987299
72997300
See Also
73007301
--------
@@ -7371,7 +7372,7 @@ def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
73717372
**kwargs
73727373
Keyword arguments control the `.Line2D` properties:
73737374
7374-
%(Line2D_kwdoc)s
7375+
%(Line2D:kwdoc)s
73757376
73767377
See Also
73777378
--------
@@ -7437,7 +7438,7 @@ def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
74377438
**kwargs
74387439
Keyword arguments control the `.Line2D` properties:
74397440
7440-
%(Line2D_kwdoc)s
7441+
%(Line2D:kwdoc)s
74417442
74427443
See Also
74437444
--------
@@ -7504,7 +7505,7 @@ def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
75047505
**kwargs
75057506
Keyword arguments control the `.Line2D` properties:
75067507
7507-
%(Line2D_kwdoc)s
7508+
%(Line2D:kwdoc)s
75087509
75097510
References
75107511
----------
@@ -7754,7 +7755,7 @@ def spy(self, Z, precision=0, marker=None, markersize=None,
77547755
For the marker style, you can pass any `.Line2D` property except
77557756
for *linestyle*:
77567757
7757-
%(Line2D_kwdoc)s
7758+
%(Line2D:kwdoc)s
77587759
"""
77597760
if marker is None and markersize is None and hasattr(Z, 'tocoo'):
77607761
marker = 's'

‎lib/matplotlib/axes/_base.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -586,7 +586,7 @@ def __init__(self, fig, rect,
586586
**kwargs
587587
Other optional keyword arguments:
588588
589-
%(Axes_kwdoc)s
589+
%(Axes:kwdoc)s
590590
591591
Returns
592592
-------
@@ -3219,7 +3219,7 @@ def grid(self, visible=None, which='major', axis='both', **kwargs):
32193219
32203220
Valid keyword arguments are:
32213221
3222-
%(Line2D_kwdoc)s
3222+
%(Line2D:kwdoc)s
32233223
32243224
Notes
32253225
-----

0 commit comments

Comments
 (0)