10000 Merge pull request #17752 from QuLogic/doc-normalize · matplotlib/matplotlib@224e451 · GitHub
[go: up one dir, main page]
Skip to content

Commit 224e451

Browse files
timhoffmtimhoffm
authored
Merge pull request #17752 from QuLogic/doc-normalize
Numpydoc-ify various functions
2 parents 4b22dca + f0d7a76 commit 224e451

File tree

7 files changed

+165
-114
lines changed

7 files changed

+165
-114
lines changed

‎lib/matplotlib/axes/_axes.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5329,7 +5329,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
53295329
origin=None, extent=None, *, filternorm=True, filterrad=4.0,
53305330
resample=None, url=None, **kwargs):
53315331
"""
5332-
Display data as an image; i.e. on a 2D regular raster.
5332+
Display data as an image, i.e., on a 2D regular raster.
53335333
53345334
The input may either be actual RGB(A) data, or 2D scalar data, which
53355335
will be rendered as a pseudocolor image. For displaying a grayscale

‎lib/matplotlib/colorbar.py

Lines changed: 62 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -54,25 +54,26 @@
5454

5555
_log = logging.getLogger(__name__)
5656

57-
make_axes_kw_doc = """
58-
59-
============= ====================================================
60-
Property Description
61-
============= ====================================================
62-
*orientation* vertical or horizontal
63-
*fraction* 0.15; fraction of original axes to use for colorbar
64-
*pad* 0.05 if vertical, 0.15 if horizontal; fraction
65-
of original axes between colorbar and new image axes
66-
*shrink* 1.0; fraction by which to multiply the size of the colorbar
67-
*aspect* 20; ratio of long to short dimensions
68-
*anchor* (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal;
69-
the anchor point of the colorbar axes
70-
*panchor* (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal;
71-
the anchor point of the colorbar parent axes. If
72-
False, the parent axes' anchor will be unchanged
73-
============= ====================================================
74-
57+
_make_axes_param_doc = """
58+
fraction : float, default: 0.15
59+
Fraction of original axes to use for colorbar.
60+
shrink : float, default: 1.0
61+
Fraction by which to multiply the size of the colorbar.
62+
aspect : float, default: 20
63+
Ratio of long to short dimensions.
64+
"""
65+
_make_axes_other_param_doc = """
66+
pad : float, default: 0.05 if vertical, 0.15 if horizontal
67+
Fraction of original axes between colorbar and new image axes.
68+
anchor : (float, float), optional
69+
The anchor point of the colorbar axes.
70+
Defaults to (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal.
71+
panchor : (float, float), or *False*, optional
72+
The anchor point of the colorbar parent axes. If *False*, the parent
73+
axes' anchor will be unchanged.
74+
Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal.
7575
"""
76+
make_axes_kw_doc = _make_axes_param_doc + _make_axes_other_param_doc
7677

7778
colormap_kw_doc = """
7879
@@ -1362,7 +1363,7 @@ def remove(self):
13621363
ax.set_subplotspec(subplotspec)
13631364

13641365

1365-
@docstring.Substitution(make_axes_kw_doc)
1366+
@docstring.Substitution(_make_axes_param_doc, _make_axes_other_param_doc)
13661367
def make_axes(parents, location=None, orientation=None, fraction=0.15,
13671368
shrink=1.0, aspect=20, **kw):
13681369
"""
@@ -1371,21 +1372,33 @@ def make_axes(parents, location=None, orientation=None, fraction=0.15,
13711372
The axes is placed in the figure of the *parents* axes, by resizing and
13721373
repositioning *parents*.
13731374
1374-
Keyword arguments may include the following (with defaults):
1375+
Parameters
1376+
----------
1377+
parents : `~.axes.Axes` or list of `~.axes.Axes`
1378+
The Axes to use as parents for placing the colorbar.
13751379
1376-
location : None or {'left', 'right', 'top', 'bottom'}
1377-
The position, relative to *parents*, where the colorbar axes
1378-
should be created. If None, the value will either come from the
1379-
given ``orientation``, else it will default to 'right'.
1380+
location : None or {'left', 'right', 'top', 'bottom'}
1381+
The position, relative to *parents*, where the colorbar axes
1382+
should be created. If None, the value will either come from the
1383+
given ``orientation``, else it will default to 'right'.
13801384
1381-
orientation : None or {'vertical', 'horizontal'}
1382-
The orientation of the colorbar. Typically, this keyword shouldn't
1383-
be used, as it can be derived from the ``location`` keyword.
1385+
orientation : None or {'vertica F438 l', 'horizontal'}
1386+
The orientation of the colorbar. Typically, this keyword shouldn't
1387+
be used, as it can be derived from the ``location`` keyword.
13841388
13851389
%s
13861390
1387-
Returns (cax, kw), the child axes and the reduced kw dictionary to be
1388-
passed when creating the colorbar instance.
1391+
Returns
1392+
-------
1393+
cax : `~.axes.Axes`
1394+
The child axes.
1395+
kw : dict
1396+
The reduced keyword dictionary to be passed when creating the colorbar
1397+
instance.
1398+
1399+
Other Parameters
1400+
----------------
1401+
%s
13891402
"""
13901403
locations = ["left", "right", "top", "bottom"]
13911404
if orientation is not None and location is not None:
@@ -1519,7 +1532,7 @@ def make_axes(parents, location=None, orientation=None, fraction=0.15,
15191532
return cax, kw
15201533

15211534

1522-
@docstring.Substitution(make_axes_kw_doc)
1535+
@docstring.Substitution(_make_axes_param_doc, _make_axes_other_param_doc)
15231536
def make_axes_gridspec(parent, *, fraction=0.15, shrink=1.0, aspect=20, **kw):
15241537
"""
15251538
Create a `~.SubplotBase` suitable for a colorbar.
@@ -1530,30 +1543,40 @@ def make_axes_gridspec(parent, *, fraction=0.15, shrink=1.0, aspect=20, **kw):
15301543
This function is similar to `.make_axes`. Primary differences are
15311544
15321545
- `.make_axes_gridspec` only handles the *orientation* keyword
1533-
and cannot handle the "location" keyword.
1546+
and cannot handle the *location* keyword.
15341547
15351548
- `.make_axes_gridspec` should only be used with a `.SubplotBase` parent.
15361549
15371550
- `.make_axes` creates an `~.axes.Axes`; `.make_axes_gridspec` creates a
15381551
`.SubplotBase`.
15391552
15401553
- `.make_axes` updates the position of the parent. `.make_axes_gridspec`
1541-
replaces the ``grid_spec`` attribute of the parent with a new one.
1554+
replaces the ``grid_spec`` attribute of the parent with a new one.
15421555
15431556
While this function is meant to be compatible with `.make_axes`,
15441557
there could be some minor differences.
15451558
1546-
Keyword arguments may include the following (with defaults):
1547-
1548-
*orientation*
1549-
'vertical' or 'horizontal'
1559+
Parameters
1560+
----------
1561+
parent : `~.axes.Axes`
1562+
The Axes to use as parent for placing the colorbar.
15501563
15511564
%s
15521565
1553-
All but the first of these are stripped from the input kw set.
1566+
Returns
1567+
-------
1568+
cax : `~.axes.SubplotBase`
1569+
The child axes.
1570+
kw : dict
1571+
The reduced keyword dictionary to be passed when creating the colorbar
1572+
instance.
15541573
1555-
Returns (cax, kw), the child axes and the reduced kw dictionary to be
1556-
passed when creating the colorbar instance.
1574+
Other Parameters
1575+
----------------
1576+
orientation : {'vertical', 'horizontal'}, default: 'vertical'
1577+
The orientation of the colorbar.
1578+
1579+
%s
15571580
"""
15581581

15591582
orientation = kw.setdefault('orientation', 'vertical')

‎lib/matplotlib/dates.py

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -607,8 +607,12 @@ class IndexDateFormatter(ticker.Formatter):
607607

608608
def __init__(self, t, fmt, tz=None):
609609
"""
610-
*t* is a sequence of dates (floating point days). *fmt* is a
611-
`~datetime.datetime.strftime` format string.
610+
Parameters
611+
----------
612+
t : list of float
613+
A sequence of dates (floating point days).
614+
fmt : str
615+
A `~datetime.datetime.strftime` format string.
612616
"""
613617
if tz is None:
614618
tz = _get_rc_timezone()

‎lib/matplotlib/legend.py

Lines changed: 27 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -941,13 +941,21 @@ def set_bbox_to_anchor(self, bbox, transform=None):
941941
"""
942942
Set the bbox that the legend will be anchored to.
943943
944-
*bbox* can be
945-
946-
- A `.BboxBase` instance
947-
- A tuple of ``(left, bottom, width, height)`` in the given transform
948-
(normalized axes coordinate if None)
949-
- A tuple of ``(left, bottom)`` where the width and height will be
950-
assumed to be zero.
944+
Parameters
945+
----------
946+
bbox : `~matplotlib.transforms.BboxBase` or tuple
947+
The bounding box can be specified in the following ways:
948+
949+
- A `.BboxBase` instance
950+
- A tuple of ``(left, bottom, width, height)`` in the given
951+
transform (normalized axes coordinate if None)
952+
- A tuple of ``(left, bottom)`` where the width and height will be
953+
assumed to be zero.
954+
- *None*, to remove the bbox anchoring, and use the parent bbox.
955+
956+
transform : `~matplotlib.transforms.Transform`, optional
957+
A transform to apply to the bounding box. If not specified, this
958+
will use a transform to the bounding box of the parent.
951959
"""
952960
if bbox is None:
953961
self._bbox_to_anchor = None
@@ -978,13 +986,16 @@ def _get_anchored_bbox(self, loc, bbox, parentbbox, renderer):
978986
Place the *bbox* inside the *parentbbox* according to a given
979987
location code. Return the (x, y) coordinate of the bbox.
980988
981-
- loc: a location code in range(1, 11).
982-
This corresponds to the possible values for self._loc, excluding
983-
"best".
989+
Parameters
990+
----------
991+
loc : int
992+
A location code in range(1, 11). This corresponds to the possible
993+
values for ``self._loc``, excluding "best".
994+
bbox : `~matplotlib.transforms.Bbox`
995+
bbox to be placed, in display coordinates.
996+
parentbbox : `~matplotlib.transforms.Bbox`
997+
A parent box which will contain the bbox, in display coordinates.
984998
985-
- bbox: bbox to be placed, display coordinate units.
986-
- parentbbox: a parent box which will contain the bbox. In
987-
display coordinates.
988999
"""
9891000
assert loc in range(1, 11) # called only internally
9901001

@@ -1079,8 +1090,9 @@ def set_draggable(self, state, use_blit=False, update='loc'):
10791090
10801091
Returns
10811092
-------
1082-
If *state* is ``True`` this returns the `~.DraggableLegend` helper
1083-
instance. Otherwise this returns ``None``.
1093+
`.DraggableLegend` or *None*
1094+
If *state* is ``True`` this returns the `.DraggableLegend` helper
1095+
instance. Otherwise this returns *None*.
10841096
"""
10851097
if state:
10861098
if self._draggable is None:

‎lib/matplotlib/lines.py

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1493,8 +1493,12 @@ def process_selected(self, ind, xs, ys):
14931493
Default "do nothing" implementation of the
14941494
:meth:`process_selected` method.
14951495
1496-
*ind* are the indices of the selected vertices. *xs* and *ys*
1497-
are the coordinates of the selected vertices.
1496+
Parameters
1497+
----------
1498+
ind : list of int
1499+
The indices of the selected vertices.
1500+
xs, ys : array-like
1501+
The coordinates of the selected vertices.
14981502
"""
14991503
pass
15001504

‎lib/matplotlib/offsetbox.py

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -142,10 +142,15 @@ def _get_aligned_offsets(hd_list, height, align="baseline"):
142142
*mode*. xdescent is analogous to the usual descent, but along the
143143
x-direction. xdescent values are currently ignored.
144144
145-
*hd_list* : list of (width, xdescent) of boxes to be aligned.
146-
*sep* : spacing between boxes
147-
*height* : Intended total length. None if not used.
148-
*align* : align mode. 'baseline', 'top', 'bottom', or 'center'.
145+
Parameters
146+
----------
147+
hd_list
148+
List of (height, xdescent) of boxes to be aligned.
149+
height : float or None
150+
Intended total length. If None, the maximum of the heights in *hd_list*
151+
is used.
152+
align : {'baseline', 'left', 'top', 'right', 'bottom', 'center'}
153+
Align mode.
149154
"""
150155

151156
if height is None:

0 commit comments

Comments
 (0)
0