8000 Auto-generate required kwdoc entries into docstring.interpd. · matplotlib/matplotlib@2bb1343 · GitHub
[go: up one dir, main page]
Skip to content

Commit 2bb1343

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 interpol 8000 ation 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 303873f commit 2bb1343

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`, 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
@@ -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
@@ -4740,7 +4741,7 @@ def reduce_C_function(C: array) -> float
47404741
**kwargs : `~matplotlib.collections.PolyCollection` properties
47414742
All other keyword arguments are passed on to `.PolyCollection`:
47424743
4743-
%(PolyCollection_kwdoc)s
4744+
%(PolyCollection:kwdoc)s
47444745
47454746
"""
47464747
self._process_unit_info([("x", x), ("y", y)], kwargs, convert=False)
@@ -5249,7 +5250,7 @@ def _fill_between_x_or_y(
52495250
All other keyword arguments are passed on to `.PolyCollection`.
52505251
They control the `.Polygon` properties:
52515252
5252-
%(PolyCollection_kwdoc)s
5253+
%(PolyCollection:kwdoc)s
52535254
52545255
See Also
52555256
--------
@@ -5847,7 +5848,7 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
58475848
Additionally, the following arguments are allowed. They are passed
58485849
along to the `~matplotlib.collections.PolyCollection` constructor:
58495850
5850-
%(PolyCollection_kwdoc)s
5851+
%(PolyCollection:kwdoc)s
58515852
58525853
See Also
58535854
--------
@@ -6092,7 +6093,7 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
60926093
Additionally, the following arguments are allowed. They are passed
60936094
along to the `~matplotlib.collections.QuadMesh` constructor:
60946095
6095-
%(QuadMesh_kwdoc)s
6096+
%(QuadMesh:kwdoc)s
60966097
60976098
See Also
60986099
--------
@@ -7133,7 +7134,7 @@ def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
71337134
**kwargs
71347135
Keyword arguments control the `.Line2D` properties:
71357136
7136-
%(Line2D_kwdoc)s
7137+
%(Line2D:kwdoc)s
71377138
71387139
See Also
71397140
--------
@@ -7246,7 +7247,7 @@ def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
72467247
**kwargs
72477248
Keyword arguments control the `.Line2D` properties:
72487249
7249-
%(Line2D_kwdoc)s
7250+
%(Line2D:kwdoc)s
72507251
72517252
See Also
72527253
--------
@@ -7336,7 +7337,7 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
73367337
**kwargs
73377338
Keyword arguments control the `.Line2D` properties:
73387339
7339-
%(Line2D_kwdoc)s
7340+
%(Line2D:kwdoc)s
73407341
73417342
See Also
73427343
--------
@@ -7413,7 +7414,7 @@ def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
74137414
**kwargs
74147415
Keyword arguments control the `.Line2D` properties:
74157416
7416-
%(Line2D_kwdoc)s
7417+
%(Line2D:kwdoc)s
74177418
74187419
See Also
74197420
--------
@@ -7479,7 +7480,7 @@ def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
74797480
**kwargs
74807481
Keyword arguments control the `.Line2D` properties:
74817482
7482-
%(Line2D_kwdoc)s
7483+
%(Line2D:kwdoc)s
74837484
74847485
See Also
74857486
--------
@@ -7546,7 +7547,7 @@ def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
75467547
**kwargs
75477548
Keyword arguments control the `.Line2D` properties:
75487549
7549-
%(Line2D_kwdoc)s
7550+
%(Line2D:kwdoc)s
75507551
75517552
References
75527553
----------
@@ -7796,7 +7797,7 @@ def spy(self, Z, precision=0, marker=None, markersize=None,
77967797
For the marker style, you can pass any `.Line2D` property except
77977798
for *linestyle*:
77987799
7799-
%(Line2D_kwdoc)s
7800+
%(Line2D:kwdoc)s
78007801
"""
78017802
if marker is None and markersize is None and hasattr(Z, 'tocoo'):
78027803
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
-------
@@ -3217,7 +3217,7 @@ def grid(self, b=None, which='major', axis='both', **kwargs):
32173217
32183218
Valid keyword arguments are:
32193219
3220-
%(Line2D_kwdoc)s
3220+
%(Line2D:kwdoc)s
32213221
32223222
Notes
32233223
-----

‎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 436E 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
@@ -2097,12 +2097,3 @@ def draw(self, renderer):
20972097
gc.restore()
20982098
renderer.close_group(self.__class__.__name__)
20992099
self.stale = False
2100-
2101-
2102-
_artist_kwdoc = artist.kwdoc(Collection)
2103-
for k in ('QuadMesh', 'TriMesh', 'PolyCollection', 'BrokenBarHCollection',
2104-
'RegularPolyCollection', 'PathCollection',
2105-
'StarPolygonCollection', 'PatchCollection',
2106-
'CircleCollection', 'Collection',):
2107-
docstring.interpd.update({f'{k}_kwdoc': _artist_kwdoc})
2108-
docstring.interpd.update(LineCollection_kwdoc=artist.kwdoc(LineCollection))

0 commit comments

Comments
 (0)
0