10000 Cleanup widgets docstrings. · matplotlib/matplotlib@3f9280c · GitHub
[go: up one dir, main page]
Skip to content

Commit 3f9280c

Browse files
anntzeranntzer
committed
Cleanup widgets docstrings.
1 parent 30ee939 commit 3f9280c

File tree

1 file changed

+64
-89
lines changed

1 file changed

+64
-89
lines changed

‎lib/matplotlib/widgets.py

Lines changed: 64 additions & 89 deletions
2443
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
===================
44
55
Widgets that are designed to work for any of the GUI backends.
6-
All of these widgets require you to predefine a :class:`matplotlib.axes.Axes`
7-
instance and pass that as the first arg. matplotlib doesn't try to
6+
All of these widgets require you to predefine a `matplotlib.axes.Axes`
7+
instance and pass that as the first parameter. Matplotlib doesn't try to
88
be too smart with respect to layout -- you will have to figure out how
99
wide and tall you want your Axes to be to accommodate your widget.
1010
"""
@@ -141,9 +141,9 @@ class Button(AxesWidget):
141141
Attributes
142142
----------
143143
ax
144-
The :class:`matplotlib.axes.Axes` the button renders into.
144+
The `matplotlib.axes.Axes` the button renders into.
145145
label
146-
A :class:`matplotlib.text.Text` instance.
146+
A `matplotlib.text.Text` instance.
147147
color
148148
The color of the button when not hovering.
149149
hovercolor
@@ -281,10 +281,10 @@ def __init__(self, ax, label, valmin, valmax, valinit=0.5, valfmt='%1.2f',
281281
Used to format the slider value, fprint format string.
282282
283283
closedmin : bool, optional, default: True
284-
Indicate whether the slider interval is closed on the bottom.
284+
Whether the slider interval is closed on the bottom.
285285
286286
closedmax : bool, optional, default: True
287-
Indicate whether the slider interval is closed on the top.
287+
Whether the slider interval is closed on the top.
288288
289289
slidermin : Slider, optional, default: None
290290
Do not allow the current slider to have a value less than
@@ -300,15 +300,15 @@ def __init__(self, ax, label, valmin, valmax, valinit=0.5, valfmt='%1.2f',
300300
valstep : float, optional, default: None
301301
If given, the slider will snap to multiples of `valstep`.
302302
303-
orientation : str, 'horizontal' or 'vertical', default: 'horizontal'
303+
orientation : {'horizontal', 'vertical'}, default: 'horizontal'
304304
The orientation of the slider.
305305
306306
Notes
307307
-----
308308
Additional kwargs are passed on to ``self.poly`` which is the
309-
:class:`~matplotlib.patches.Rectangle` that draws the slider
310-
knob. See the :class:`~matplotlib.patches.Rectangle` documentation for
311-
valid property names (e.g., `facecolor`, `edgecolor`, `alpha`).
309+
`~matplotlib.patches.Rectangle` that draws the slider knob. See the
310+
`.Rectangle` documentation for valid property names (``facecolor``,
311+
``edgecolor``, ``alpha``, etc.).
312312
"""
313313
if ax.name == '3d':
314314
raise ValueError('Sliders cannot be added to 3D Axes')
@@ -501,44 +501,41 @@ def reset(self):
501501

502502

503503
class CheckButtons(AxesWidget):
504-
"""
504+
r"""
505505
A GUI neutral set of check buttons.
506506
507507
For the check buttons to remain responsive you must keep a
508508
reference to this object.
509509
510-
The following attributes are exposed
511-
512-
*ax*
513-
The :class:`matplotlib.axes.Axes` instance the buttons are
514-
located in
515-
516-
*labels*
517-
List of :class:`matplotlib.text.Text` instances
510+
Connect to the CheckButtons with the :meth:`on_clicked` method
518511
519-
*lines*
512+
Attributes
513+
----------
514+
ax
515+
The `matplotlib.axes.Axes` the button are located in.
516+
labels
517+
A list of `matplotlib.text.Text`\ s.
518+
lines
520519
List of (line1, line2) tuples for the x's in the check boxes.
521520
These lines exist for each box, but have ``set_visible(False)``
522521
when its box is not checked.
523-
524-
*rectangles*
525-
List of :class:`matplotlib.patches.Rectangle` instances
526-
527-
Connect to the CheckButtons with the :meth:`on_clicked` method
522+
rectangles
523+
A list of `matplotlib.patches.Rectangle`\ s.
528524
"""
525+
529526
def __init__(self, ax, labels, actives=None):
530527
"""
531-
Add check buttons to :class:`matplotlib.axes.Axes` instance *ax*
528+
Add check buttons to `matplotlib.axes.Axes` instance *ax*
532529
533530
Parameters
534531
----------
535532
ax : `~matplotlib.axes.Axes`
536533
The parent axes for the widget.
537534
538-
labels : List[str]
535+
labels : list of str
539536
The labels of the check buttons.
540537
541-
actives : List[bool], optional
538+
actives : list of bool, optional
542539
The initial check states of the buttons. The list must have the
543540
same length as *labels*. If not given, all buttons are unchecked.
544541
"""
@@ -659,24 +656,21 @@ class TextBox(AxesWidget):
659656
660657
For the text box to remain responsive you must keep a reference to it.
661658
662-
The following attributes are accessible:
663-
664-
*ax*
665-
The :class:`matplotlib.axes.Axes` the button renders into.
666-
667-
*label*
668-
A :class:`matplotlib.text.Text` instance.
669-
670-
*color*
671-
The color of the text box when not hovering.< F438 /span>
672-
673-
*hovercolor*
674-
The color of the text box when hovering.
675-
676659
Call :meth:`on_text_change` to be updated whenever the text changes.
677660
678661
Call :meth:`on_submit` to be updated whenever the user hits enter or
679662
leaves the text entry field.
663+
664+
Attributes
665+
----------
666+
ax
667+
The `matplotlib.axes.Axes` the button renders into.
668+
label
669+
A `matplotlib.text.Text` instance.
670+
color
671+
The color of the button when not hovering.
672+
hovercolor
673+
The color of the button when hovering.
680674
"""
681675

682676
def __init__(self, ax, label, initial='',
@@ -686,19 +680,14 @@ def __init__(self, ax, label, initial='',
686680
----------
687681
ax : `~matplotlib.axes.Axes`
688682
The `~.axes.Axes` instance the button will be placed into.
689-
690683
label : str
691-
Label for this text box. Accepts string.
692-
684+
Label for this text box.
693685
initial : str
694686
Initial value in the text box.
695-
696687
color : color
697688
The color of the box.
698-
699689
hovercolor : color
700690
The color of the box when the mouse is over it.
701-
702691
label_pad : float
703692
The distance between the label and the right side of the textbox.
704693
"""
@@ -1108,19 +1097,18 @@ def disconnect(self, cid):
11081097

11091098
class SubplotTool(Widget):
11101099
"""
1111-
A tool to adjust the subplot params of a :class:`matplotlib.figure.Figure`.
1100+
A tool to adjust the subplot params of a `matplotlib.figure.Figure`.
11121101
"""
1102+
11131103
def __init__(self, targetfig, toolfig):
11141104
"""
1115-
*targetfig*
1105+
Parameters
1106+
----------
1107+
targetfig : `.Figure`
11161108
The figure instance to adjust.
1117-
1118-
*toolfig*
1119-
The figure instance to embed the subplot tool into. If
1120-
*None*, a default figure will be created. If you are using
1121-
this from the GUI
1109+
toolfig : `.Figure`
1110+
The figure instance to embed the subplot tool into.
11221111
"""
1123-
# FIXME: The docstring seems to just abruptly end without...
11241112

11251113
self.targetfig = targetfig
11261114
toolfig.subplots_adjust(left=0.2, right=0.9)
@@ -1667,35 +1655,31 @@ class SpanSelector(_SelectorWidget):
16671655
16681656
Parameters
16691657
----------
1670-
ax : :class:`matplotlib.axes.Axes` object
1658+
ax : `matplotlib.axes.Axes` object
16711659
16721660
onselect : func(min, max), min/max are floats
16731661
1674-
direction : "horizontal" or "vertical"
1675-
The axis along which to draw the span selector
1662+
direction : {"horizontal", "vertical"}
1663+
The direction along which to draw the span selector.
16761664
16771665
minspan : float, default is None
1678-
If selection is less than *minspan*, do not call *onselect*
1666+
If selection is less than *minspan*, do not call *onselect*.
16791667
16801668
useblit : bool, default is False
1681-
If True, use the backend-dependent blitting features for faster
< F987 /td>
1682-
canvas updates.
1669+
If True, use the backend-dependent blitting features for faster
1670+
canvas updates.
16831671
16841672
rectprops : dict, default is None
1685-
Dictionary of :class:`matplotlib.patches.Patch` properties
1673+
Dictionary of `matplotlib.patches.Patch` properties.
16861674
16871675
onmove_callback : func(min, max), min/max are floats, default is None
1688-
Called on mouse move while the span is being selected
1676+
Called on mouse move while the span is being selected.
16891677
16901678
span_stays : bool, default is False
1691-
If True, the span stays visible after the mouse is released
1679+
If True, the span stays visible after the mouse is released.
16921680
1693-
button : int or list of ints
1694-
Determines which mouse buttons activate the span selector:
1695-
1696-
- 1: left mouse button
1697-
- 2: center mouse button (scroll wheel)
1698-
- 3: right mouse button
1681+
button : `.MouseButton` or list of `.MouseButton`
1682+
The mouse buttons which activate the span selector.
16991683
17001684
Examples
17011685
--------
@@ -1885,14 +1869,14 @@ class ToolHandles:
18851869
18861870
Parameters
18871871
----------
1888-
ax : :class:`matplotlib.axes.Axes`
1872+
ax : `matplotlib.axes.Axes`
18891873
Matplotlib axes where tool handles are displayed.
18901874
x, y : 1D arrays
18911875
Coordinates of control handles.
18921876
marker : str
18931877
Shape of marker used to display handle. See `matplotlib.pyplot.plot`.
18941878
marker_props : dict
1895-
Additional marker properties. See :class:`matplotlib.lines.Line2D`.
1879+
Additional marker properties. See `matplotlib.lines.Line2D`.
18961880
"""
18971881

18981882
def __init__(self, ax, x, y, marker='o', marker_props=None, useblit=True):
@@ -2457,22 +2441,14 @@ def onselect(verts):
24572441
24582442
Parameters
2459
----------
2460-
ax : :class:`~matplotlib.axes.Axes`
2444+
ax : `~matplotlib.axes.Axes`
24612445
The parent axes for the widget.
24622446
onselect : function
24632447
Whenever the lasso is released, the *onselect* function is called and
24642448
passed the vertices of the selected path.
2465-
button : List[Int], optional
2466-
A list of integers indicating which mouse buttons should be used for
2467-
rectangle selection. You can also specify a single integer if only a
2468-
single button is desired. Default is ``None``, which does not limit
2469-
which button can be used.
2470-
2471-
Note, typically:
2472-
2473-
- 1 = left mouse button
2474-
- 2 = center mouse button (scroll wheel)
2475-
- 3 = right mouse button
2449+
button : `.MouseButton` or list of `.MouseButton`, optional
2450+
The mouse buttons used for rectangle selection. Default is ``None``,
2451+
which corresponds to all buttons.
24762452
"""
24772453

24782454
def __init__(self, ax, onselect=None, useblit=True, lineprops=None,
@@ -2535,7 +2511,7 @@ class PolygonSelector(_SelectorWidget):
25352511
25362512
Parameters
25372513
----------
2538-
ax : :class:`~matplotlib.axes.Axes`
2514+
ax : `~matplotlib.axes.Axes`
25392515
The parent axes for the widget.
25402516
onselect : function
25412517
When a polygon is completed or modified after completion,
@@ -2732,10 +2708,9 @@ class Lasso(AxesWidget):
27322708
Selection curve of an arbitrary shape.
27332709
27342710
The selected path can be used in conjunction with
2735-
:func:`~matplotlib.path.Path.contains_point` to select data points
2736-
from an image.
2711+
`~matplotlib.path.Path.contains_point` to select data points from an image.
27372712
2738-
Unlike :class:`LassoSelector`, this must be initialized with a starting
2713+
Unlike `LassoSelector`, this must be initialized with a starting
27392714
point `xy`, and the `Lasso` events are destroyed upon release.
27402715
27412716
Parameters

0 commit comments

Comments
 (0)
0