8000 Improve properties formatting in interpolated docstrings. · matplotlib/matplotlib@7cac077 · GitHub
[go: up one dir, main page]

Skip to content

Commit 7cac077

Browse files
committed
Improve properties formatting in interpolated docstrings.
This makes docstring interpolation a bit less sensitive to the indent where the inserted string goes. For example, the docstring of `add_subplot` goes from ``` **kwargs This method also takes the keyword arguments for the returned axes base class. The keyword arguments for the rectilinear base class `~.axes.Axes` can be found in the following table but there might also be other keyword arguments if another projection is used. adjustable: {'box', 'datalim'} agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array alpha: float or None ... ``` to ``` **kwargs This method also takes the keyword arguments for the returned axes base class. The keyword arguments for the rectilinear base class `~.axes.Axes` can be found in the following table but there might also be other keyword arguments if another projection is used. Properties: adjustable: {'box', 'datalim'} agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array alpha: float or None ``` Note that this does not affect sphinx rendering as that uses pprint_setters_rest. Note that whether the properties list is indented relative to the "Properties" header depends on the indent where the inserted string goes (lines starting from the second one are *always* indented by 4 characters (8 looks like too much), but I think it's still an (incremental) improvement. Also make sure that the property list is preceded by a newline.
1 parent cc7c347 commit 7cac077

File tree

10 files changed

+31
-28
lines changed

10 files changed

+31
-28
lines changed

lib/matplotlib/artist.py

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1575,12 +1575,10 @@ def kwdoc(artist):
15751575
:rc:`docstring.hardcopy` is False and as a rst table (intended for
15761576
use in Sphinx) if it is True.
15771577
"""
1578-
hardcopy = matplotlib.rcParams['docstring.hardcopy']
1579-
if hardcopy:
1580-
return '\n'.join(ArtistInspector(artist).pprint_setters_rest(
1581-
leadingspace=4))
1582-
else:
1583-
return '\n'.join(ArtistInspector(artist).pprint_setters(
1584-
leadingspace=2))
1578+
ai = ArtistInspector(artist)
1579+
return ('\n'.join(ai.pprint_setters_rest(leadingspace=4))
1580+
if matplotlib.rcParams['docstring.hardcopy'] else
1581+
'Properties:\n' + '\n'.join(ai.pprint_setters(leadingspace=4)))
1582+
15851583

15861584
docstring.interpd.update(Artist=kwdoc(Artist))

lib/matplotlib/axes/_axes.py

Lines changed: 0 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -394,7 +394,6 @@ def legend(self, *args, **kwargs):
394394
--------
395395
396396
.. plot:: gallery/text_labels_and_annotations/legend.py
397-
398397
"""
399398
handles, labels, extra_args, kwargs = mlegend._parse_legend_args(
400399
[self],
@@ -646,15 +645,12 @@ def secondary_xaxis(self, location, *, functions=None, **kwargs):
646645
ax.loglog(range(1, 360, 5), range(1, 360, 5))
647646
ax.set_xlabel('frequency [Hz]')
648647
649-
650648
def invert(x):
651649
return 1 / x
652650
653651
secax = ax.secondary_xaxis('top', functions=(invert, invert))
654652
secax.set_xlabel('Period [s]')
655653
plt.show()
656-
657-
658654
"""
659655
if (location in ['top', 'bottom'] or isinstance(location, Number)):
660656
secondary_ax = SecondaryAxis(self, 'x', location, functions,
@@ -687,7 +683,6 @@ def secondary_yaxis(self, location, *, functions=None, **kwargs):
687683
secax = ax.secondary_yaxis('right', functions=(np.deg2rad,
688684
np.rad2deg))
689685
secax.set_ylabel('radians')
690-
691686
"""
692687
if location in ['left', 'right'] or isinstance(location, Number):
693688
secondary_ax = SecondaryAxis(self, 'y', location,
@@ -846,7 +841,6 @@ def axhline(self, y=0, xmin=0, xmax=1, **kwargs):
846841
the xrange::
847842
848843
>>> axhline(y=.5, xmin=0.25, xmax=0.75)
849-
850844
"""
851845
if "transform" in kwargs:
852846
raise ValueError(
@@ -1715,15 +1709,13 @@ def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False,
17151709
17161710
%(_Line2D_docstr)s
17171711
1718-
17191712
See Also
17201713
--------
17211714
matplotlib.dates : Helper functions on dates.
17221715
matplotlib.dates.date2num : Convert dates to num.
17231716
matplotlib.dates.num2date : Convert num to dates.
17241717
matplotlib.dates.drange : Create an equally spaced sequence of dates.
17251718
1726-
17271719
Notes
17281720
-----
17291721
If you are using custom date tickers and formatters, it may be
@@ -2277,7 +2269,6 @@ def bar(self, x, height, width=0.8, bottom=None, *, align="center",
22772269
Other optional kwargs:
22782270
22792271
%(Rectangle)s
2280-
22812272
"""
22822273
kwargs = cbook.normalize_kwargs(kwargs, mpatches.Patch)
22832274
color = kwargs.pop('color', None)
@@ -2563,7 +2554,6 @@ def barh(self, y, width, height=0.8, left=None, *, align="center",
25632554
Other optional kwargs:
25642555
25652556
%(Rectangle)s
2566-
25672557
"""
25682558
kwargs.setdefault('orientation', 'horizontal')
25692559
patches = self.bar(x=left, height=height, width=width, bottom=y,
@@ -3183,7 +3173,6 @@ def errorbar(self, x, y, yerr=None, xerr=None,
31833173
Notes
31843174
-----
31853175
.. [Notes section required for data comment. See #10189.]
3186-
31873176
"""
31883177
kwargs = cbook.normalize_kwargs(kwargs, mlines.Line2D)
31893178
# anything that comes in as 'None', drop so the default thing
@@ -4631,7 +4620,6 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
46314620
:class:`~matplotlib.collections.Collection` parameters:
46324621
46334622
%(Collection)s
4634-
46354623
"""
46364624
self._process_unit_info(xdata=x, ydata=y, kwargs=kwargs)
46374625

@@ -6050,7 +6038,6 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
60506038
60516039
%(QuadMesh)s
60526040
6053-
60546041
See Also
60556042
--------
60566043
pcolor : An alternative implementation with slightly different

lib/matplotlib/axes/_base.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -441,6 +441,7 @@ def __init__(self, fig, rect,
441441
442442
**kwargs
443443
Other optional keyword arguments:
444+
444445
%(Axes)s
445446
446447
Returns

lib/matplotlib/figure.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1167,6 +1167,7 @@ def add_axes(self, *args, **kwargs):
11671167
the following table but there might also be other keyword
11681168
arguments if another projection is used, see the actual axes
11691169
class.
1170+
11701171
%(Axes)s
11711172
11721173
Returns
@@ -1306,6 +1307,7 @@ def add_subplot(self, *args, **kwargs):
13061307
rectilinear base class `~.axes.Axes` can be found in
13071308
the following table but there might also be other keyword
13081309
arguments if another projection is used.
1310+
13091311
%(Axes)s
13101312
13111313
Returns
@@ -1855,6 +1857,7 @@ def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
18551857
----------------
18561858
**kwargs : `~matplotlib.text.Text` properties
18571859
Other miscellaneous text parameters.
1860+
18581861
%(Text)s
18591862
18601863
Returns

lib/matplotlib/patches.py

Lines changed: 11 additions & 7 deletions
EED3
Original file line numberDiff line numberDiff line change
@@ -605,6 +605,7 @@ def __init__(self, patch, ox, oy, props=None, **kwargs):
605605
but darkened.
606606
607607
kwargs are
608+
608609
%(Patch)s
609610
"""
610611
Patch.__init__(self)
@@ -686,6 +687,7 @@ def __init__(self, xy, width, height, angle=0.0, **kwargs):
686687
Notes
687688
-----
688689
Valid kwargs are:
690+
689691
%(Patch)s
690692
"""
691693

@@ -853,6 +855,7 @@ def __init__(self, xy, numVertices, radius=5, orientation=0,
853855
rotates the polygon (in radians).
854856
855857
Valid kwargs are:
858+
856859
%(Patch)s
857860
"""
858861
self._xy = xy
@@ -930,6 +933,7 @@ def __init__(self, path, **kwargs):
930933
*path* is a :class:`matplotlib.path.Path` object.
931934
932935
Valid kwargs are:
936+
933937
%(Patch)s
934938
"""
935939
Patch.__init__(self, **kwargs)
@@ -956,6 +960,7 @@ def __init__(self, xy, closed=True, **kwargs):
956960
starting and ending points are the same.
957961
958962
Valid kwargs are:
963+
959964
%(Patch)s
960965
"""
961966
Patch.__init__(self, **kwargs)
@@ -1232,8 +1237,8 @@ def __init__(self, x, y, dx, dy, width=0.001, length_includes_head=False,
12321237
instead of ending at coordinate 0.
12331238
12341239
Other valid kwargs (inherited from :class:`Patch`) are:
1235-
%(Patch)s
12361240
1241+
%(Patch)s
12371242
"""
12381243
if head_width is None:
12391244
head_width = 3 * width
@@ -1330,8 +1335,8 @@ def __init__(self, figure, xytip, xybase,
13301335
The width of the base of the arrow head in points
13311336
13321337
Valid kwargs are:
1333-
%(Patch)s
13341338
1339+
%(Patch)s
13351340
"""
13361341
self.xytip = xytip
13371342
self.xybase = xybase
@@ -1415,8 +1420,8 @@ def __init__(self, xy, radius=5,
14151420
see :class:`~matplotlib.patches.Circle`.
14161421
14171422
Valid kwargs are:
1418-
%(Patch)s
14191423
1424+
%(Patch)s
14201425
"""
14211426
RegularPolygon.__init__(self, xy,
14221427
resolution,
@@ -1452,6 +1457,7 @@ def __init__(self, xy, width, height, angle=0, **kwargs):
14521457
Notes
14531458
-----
14541459
Valid keyword arguments are
1460+
14551461
%(Patch)s
14561462
"""
14571463
Patch.__init__(self, **kwargs)
@@ -1526,8 +1532,8 @@ def __init__(self, xy, radius=5, **kwargs):
15261532
and is much closer to a scale-free circle.
15271533
15281534
Valid kwargs are:
1529-
%(Patch)s
15301535
1536+
%(Patch)s
15311537
"""
15321538
Ellipse.__init__(self, xy, radius * 2, radius * 2, **kwargs)
15331539
self.radius = radius
@@ -1607,7 +1613,6 @@ def __init__(self, xy, width, height, angle=0.0,
16071613
not supported.
16081614
16091615
%(Patch)s
1610-
16111616
"""
16121617
fill = kwargs.setdefault('fill', False)
16131618
if fill:
@@ -2480,6 +2485,7 @@ def __init__(self, xy, width, height,
24802485
box will be stretched by the inverse of it. default=None.
24812486
24822487
Valid kwargs are:
2488+
24832489
%(Patch)s
24842490
"""
24852491

@@ -2689,7 +2695,6 @@ class ConnectionStyle(_Style):
26892695
26902696
%(AvailableConnectorstyles)s
26912697
2692-
26932698
An instance of any connection style class is an callable object,
26942699
whose call signature is::
26952700
@@ -3134,7 +3139,6 @@ class ArrowStyle(_Style):
31343139
31353140
%(AvailableArrowstyles)s
31363141
3137-
31383142
An instance of any arrow style class is a callable object,
31393143
whose call signature is::
31403144

lib/matplotlib/pyplot.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -767,6 +767,7 @@ def axes(arg=None, **kwargs):
767767
the following table but there might also be other keyword
768768
arguments if another projection is used, see the actual axes
769769
class.
770+
770771
%(Axes)s
771772
772773
Returns
@@ -917,6 +918,7 @@ def subplot(*args, **kwargs):
917918
rectilinear base class `~.axes.Axes` can be found in
918919
the following table but there might also be other keyword
919920
arguments if another projection is used.
921+
920922
%(Axes)s
921923
922924
Returns

lib/matplotlib/spines.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ def __init__(self, axes, spine_type, path, **kwargs):
3939
- *path* : the path instance used to draw the spine
4040
4141
Valid kwargs are:
42+
4243
%(Patch)s
4344
"""
4445
super().__init__(**kwargs)

lib/matplotlib/table.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,7 @@ def set_text_props(self, **kwargs):
172172
Update the text properties.
173173
174174
Valid kwargs are
175+
175176
%(Text)s
176177
"""
177178
self._text.update(kwargs)

lib/matplotlib/text.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,9 +136,9 @@ def __init__(self,
136136
Create a `.Text` instance at *x*, *y* with string *text*.
137137
138138
Valid kwargs are
139+
139140
%(Text)s
140141
"""
141-
142142
Artist.__init__(self)
143143
self._x, self._y = x, y
144144

lib/mpl_toolkits/axes_grid1/inset_locator.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,7 @@ def __init__(self, bbox, **kwargs):
151151
152152
**kwargs
153153
Patch properties. Valid arguments include:
154+
154155
%(Patch)s
155156
"""
156157
if "transform" in kwargs:
@@ -294,6 +295,7 @@ def __init__(self, bbox1, bbox2, loc1, loc2=None, **kwargs):
294295
295296
**kwargs
296297
Patch properties for the line drawn. Valid arguments include:
298+
297299
%(Patch)s
298300
"""
299301
if "transform" in kwargs:
@@ -352,6 +354,7 @@ def __init__(self, bbox1, bbox2, loc1a, loc2a, loc1b, loc2b, **kwargs):
352354
353355
**kwargs
354356
Patch properties for the line drawn:
357+
355358
%(Patch)s
356359
"""
357360
if "transform" in kwargs:
@@ -471,6 +474,7 @@ def inset_axes(parent_axes, width, height, loc='upper right',
471474
axes_kwargs : dict, optional
472475
Keyworded arguments to pass to the constructor of the inset axes.
473476
Valid arguments include:
477+
474478
%(Axes)s
475479
476480
borderpad : float, optional
@@ -588,6 +592,7 @@ def zoomed_inset_axes(parent_axes, zoom, loc='upper right',
588592
axes_kwargs : dict, optional
589593
Keyworded arguments to pass to the constructor of the inset axes.
590594
Valid arguments include:
595+
591596
%(Axes)s
592597
593598
borderpad : float, optional
@@ -644,6 +649,7 @@ def mark_inset(parent_axes, inset_axes, loc1, loc2, **kwargs):
644649
645650
**kwargs
646651
Patch properties for the lines and box drawn:
652+
647653
%(Patch)s
648654
649655
Returns

0 commit comments

Comments
 (0)
0