Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitca6e9dc

Browse files
authored
Merge pull request#20164 from anntzer/autokwdoc
Auto-generate required kwdoc entries into docstring.interpd.
2 parents8ecc571 +a0b7d83 commitca6e9dc

File tree

19 files changed

+157
-158
lines changed

19 files changed

+157
-158
lines changed

‎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
defplot(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
importnumpyasnp
1111

1212
importmatplotlibasmpl
13-
from .import_api,cbook,docstring
13+
from .import_api,cbook
1414
from .pathimportPath
1515
from .transformsimport (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
ifmpl.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
classAxes(_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
iflen(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
ifmarkerisNoneandmarkersizeisNoneandhasattr(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)
[8]ページ先頭
©2009-2025 Movatter.jp