8000 Merge pull request #20164 from anntzer/autokwdoc · matplotlib/matplotlib@ca6e9dc · GitHub
[go: up one dir, main page]
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

File tree

19 files changed

+157
-158
lines changed
  • lines.py
  • patches.py
  • pyplot.py
  • quiver.py
  • sankey.py
  • spines.py
  • table.py
  • text.py
  • mpl_toolkits

    • 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
    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
    F438
    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)
    0