8000 Auto-generate required kwdoc entries into docstring.interpd. · matplotlib/matplotlib@f42dc3a · GitHub
[go: up one dir, main page]
Skip to content
< 8000 script crossorigin="anonymous" type="application/javascript" src="https://github.githubassets.com/assets/vendors-node_modules_github_remote-form_dist_index_js-node_modules_delegated-events_dist_inde-94fd67-99b04cc350b5.js" defer="defer">

Commit f42dc3a

Browse files
anntzeranntzer
committed
Auto-generate required kwdoc entries into docstring.interpd.
This does two things: - Replace Foo_kwdoc docstring substitutions by auto-generated Foo:kwdoc substitutions, removing the need to explicitly call `docstring.interpd.update(Foo_kwdoc=artist.kwdoc(Foo))` for each artist. - Decorating a class with `docstring.interpd` will now also perform interpolation over the docstring of the class' `__init__`, making it possible to list properties here as well, instead of having to manually call `docstring.interpd` after the class has been defined. The new behavior is also explained in documenting_mpl.rst. I think it's slightly more magical, but also easier to explain...
1 parent f5880d2 commit f42dc3a

File tree

18 files changed

+131
-143
lines changed

18 files changed

+131
-143
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
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.__init__`, 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

‎lib/matplotlib/artist.py

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

1111
import matplotlib as mpl
12-
from . import _api, cbook, docstring
12+
from . import _api, cbook
1313
from .path import Path
1414
from .transforms import (Bbox, IdentityTransform, Transform, TransformedBbox,
1515
TransformedPatchPath, TransformedPath)
@@ -1684,6 +1684,3 @@ def kwdoc(artist):
16841684
return ('\n'.join(ai.pprint_setters_rest(leadingspace=4))
16851685
if mpl.rcParams['docstring.hardcopy'] else
16861686
'Properties:\n' + '\n'.join(ai.pprint_setters(leadingspace=4)))
1687-
1688-
1689-
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 @ 10000 @ 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
--------
@@ -1651,7 +1652,7 @@ def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False,
16511652
**kwargs
16521653
Keyword arguments control the `.Line2D` properties:
16531654
1654-
%(Line2D_kwdoc)s
1655+
%(Line2D:kwdoc)s
16551656
16561657
See Also
16571658
--------
@@ -2222,7 +2223,7 @@ def bar(self, x, height, width=0.8, bottom=None, *, align="center",
22222223
22232224
**kwargs : `.Rectangle` properties
22242225
2225-
%(Rectangle_kwdoc)s
2226+
%(Rectangle:kwdoc)s
22262227
22272228
See Also
22282229
--------
@@ -2497,7 +2498,7 @@ def barh(self, y, width, height=0.8, left=None, *, align="center",
24972498
24982499
**kwargs : `.Rectangle` properties
24992500
2500-
%(Rectangle_kwdoc)s
2501+
%(Rectangle:kwdoc)s
25012502
25022503
See Also
25032504
--------
@@ -2685,7 +2686,7 @@ def broken_barh(self, xranges, yrange, **kwargs):
26852686
26862687
Supported keywords:
26872688
2688-
%(BrokenBarHCollection_kwdoc)s
2689+
%(BrokenBarHCollection:kwdoc)s
26892690
"""
26902691
# process the unit information
26912692
if len(xranges):
@@ -3276,7 +3277,7 @@ def errorbar(self, x, y, yerr=None, xerr=None,
32763277
32773278
Valid kwargs for the marker properties are `.Line2D` properties:
32783279
3279-
%(Line2D_kwdoc)s
3280+
%(Line2D:kwdoc)s
32803281
"""
32813282
kwargs = cbook.normalize_kwargs(kwargs, mlines.Line2D)
32823283
# anything that comes in as 'None', drop so the default thing
@@ -4728,7 +4729,7 @@ def reduce_C_function(C: array) -> float
47284729
**kwargs : `~matplotlib.collections.PolyCollection` properties
47294730
All other keyword arguments are passed on to `.PolyCollection`:
47304731
4731-
%(PolyCollection_kwdoc)s
4732+
%(PolyCollection:kwdoc)s
47324733
47334734
"""
47344735
self._process_unit_info([("x", x), ("y", y)], kwargs, convert=False)
@@ -5237,7 +5238,7 @@ def _fill_between_x_or_y(
52375238
All other keyword arguments are passed on to `.PolyCollection`.
52385239
They control the `.Polygon` properties:
52395240
5240-
%(PolyCollection_kwdoc)s
5241+
%(PolyCollection:kwdoc)s
52415242
52425243
See Also
52435244
--------
@@ -5843,7 +5844,7 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
58435844
Additionally, the following arguments are allowed. They are passed
58445845
along to the `~matplotlib.collections.PolyCollection` constructor:
58455846
5846-
%(PolyCollection_kwdoc)s
5847+
%(PolyCollection:kwdoc)s
58475848
58485849
See Also
58495850
--------
@@ -6088,7 +6089,7 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
60886089
Additionally, the following arguments are allowed. They are passed
60896090
along to the `~matplotlib.collections.QuadMesh` constructor:
60906091
6091-
%(QuadMesh_kwdoc)s
6092+
%(QuadMesh:kwdoc)s
60926093
60936094
See Also
60946095
--------
@@ -7129,7 +7130,7 @@ def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
71297130
**kwargs
71307131
Keyword arguments control the `.Line2D` properties:
71317132
7132-
%(Line2D_kwdoc)s
7133+
%(Line2D:kwdoc)s
71337134
71347135
See Also
71357136
--------
@@ -7242,7 +7243,7 @@ def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
72427243
**kwargs
72437244
Keyword arguments control the `.Line2D` properties:
72447245
7245-
%(Line2D_kwdoc)s
7246+
%(Line2D:kwdoc)s
72467247
72477248
See Also
72487249
--------
@@ -7332,7 +7333,7 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
73327333
**kwargs
73337334
Keyword arguments control the `.Line2D` properties:
73347335
7335-
%(Line2D_kwdoc)s
7336+
%(Line2D:kwdoc)s
73367337
73377338
See Also
73387339
--------
@@ -7409,7 +7410,7 @@ def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
74097410
**kwargs
74107411
Keyword arguments control the `.Line2D` properties:
74117412
7412-
%(Line2D_kwdoc)s
7413+
%(Line2D:kwdoc)s
74137414
74147415
See Also
74157416
--------
@@ -7475,7 +7476,7 @@ def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
74757476
**kwargs
74767477
Keyword arguments control the `.Line2D` properties:
74777478
7478-
%(Line2D_kwdoc)s
7479+
%(Line2D:kwdoc)s
74797480
74807481
See Also
74817482
--------
@@ -7542,7 +7543,7 @@ def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
75427543
**kwargs
75437544
Keyword arguments control the `.Line2D` properties:
75447545
7545-
%(Line2D_kwdoc)s
7546< 10000 /td>+
%(Line2D:kwdoc)s
75467547
75477548
References
75487549
----------
@@ -7792,7 +7793,7 @@ def spy(self, Z, precision=0, marker=None, markersize=None,
77927793
For the marker style, you can pass any `.Line2D` property except
77937794
for *linestyle*:
77947795
7795-
%(Line2D_kwdoc)s
7796+
%(Line2D:kwdoc)s
77967797
"""
77977798
if marker is None and markersize is None and hasattr(Z, 'tocoo'):
77987799
marker = 's'

‎lib/matplotlib/axes/_base.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -591,7 +591,7 @@ def __init__(self, fig, rect,
591591
**kwargs
592592
Other optional keyword arguments:
593593
594-
%(Axes_kwdoc)s
594+
%(Axes:kwdoc)s
595595
596596
Returns
597597
-------
@@ -3223,7 +3223,7 @@ def grid(self, b=None, which='major', axis='both', **kwargs):
32233223
32243224
Valid keyword arguments are:
32253225
3226-
%(Line2D_kwdoc)s
3226+
%(Line2D:kwdoc)s
32273227
32283228
Notes
32293229
-----

‎lib/matplotlib/axes/_subplots.py

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
import functools
22

3-
from matplotlib import _api, docstring
4-
import matplotlib.artist as martist
3+
from matplotlib import _api
54
from matplotlib.axes._axes import Axes
65
from matplotlib.gridspec import GridSpec, SubplotSpec
76

@@ -220,9 +219,3 @@ class when called with an axes class. This is purely to allow pickling of
220219
"""
221220
subplot_class = subplot_class_factory(axes_class)
222221
return subplot_class.__new__(subplot_class)
223-
224-
225-
docstring.interpd.update(Axes_kwdoc=martist.kwdoc(Axes))
226-
docstring.dedent_interpd(Axes.__init__)
227-
228-
docstring.interpd.update(Subplot_kwdoc=martist.kwdoc(Axes))

‎lib/matplotlib/collections.py

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2132,12 +2132,3 @@ def draw(self, renderer):
21322132
gc.restore()
21332133
renderer.close_group(self.__class__.__name__)
21342134
self.stale = False
2135-
2136-
2137-
_artist_kwdoc = artist.kwdoc(Collection)
2138-
for k in ('QuadMesh', 'TriMesh', 'PolyCollection', 'BrokenBarHCollection',
2139-
'RegularPolyCollection', 'PathCollection',
2140-
'StarPolygonCollection', 'PatchCollection',
2141-
'CircleCollection', 'Collection',):
2142-
docstring.interpd.update({f'{k}_kwdoc': _artist_kwdoc})
2143-
docstring.interpd.update(LineCollection_kwdoc=artist.kwdoc(LineCollection))

0 commit comments

Comments
 (0)
0