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

Skip to content

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Commit 224e451

Browse files
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
6D4E
1383-
be used, as it can be derived from the ``location`` keyword.
1385+
orientation : None or {'vertical', '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