Skip to content

Commit b4afdb6

Browse files
QuLogicQuLogic
committed
DOC: Make backends compatible with numpydoc.
The previous changes were intended for napoleon, but that has yet to be merged. NumPyDoc supports a few less section names, and requires them to be in a specific order. Also, a little bit of whitespace change needed to render stuff properly.
1 parent 8944735 commit b4afdb6

9 files changed

Lines changed: 117 additions & 110 deletions

File tree

‎lib/matplotlib/backend_bases.py‎

Lines changed: 56 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -246,22 +246,22 @@ def draw_markers(self, gc, marker_path, marker_trans, path,
246246
that behavior, those vertices should be removed before calling
247247
this function.
248248
249+
This provides a fallback implementation of draw_markers that
250+
makes multiple calls to :meth:`draw_path`. Some backends may
251+
want to override this method in order to draw the marker only
252+
once and reuse it multiple times.
253+
249254
Parameters
250255
----------
251256
gc
252-
the :class:`GraphicsContextBase` instance
257+
The :class:`GraphicsContextBase` instance
253258
254259
marker_trans
255-
is an affine transform applied to the marker.
260+
An affine transform applied to the marker.
256261
257262
trans
258-
is an affine transform applied to the path.
263+
An affine transform applied to the path.
259264
260-
261-
This provides a fallback implementation of draw_markers that
262-
makes multiple calls to :meth:`draw_path`. Some backends may
263-
want to override this method in order to draw the marker only
264-
once and reuse it multiple times.
265265
"""
266266
for vertices, codes in path.iter_segments(trans, simplify=False):
267267
if len(vertices):
@@ -601,7 +601,8 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
601601
mtext
602602
a :class:`matplotlib.text.Text` instance
603603
604-
604+
Notes
605+
-----
605606
**backend implementers note**
606607
607608
When you are trying to determine if you have gotten your bounding box
@@ -747,19 +748,20 @@ def points_to_pixels(self, points):
747748
"""
748749
Convert points to display units
749750
750-
Parameters
751-
----------
752-
points
753-
a float or a numpy array of float
754-
755-
756-
return points converted to pixels
757-
758751
You need to override this function (unless your backend
759752
doesn't have a dpi, e.g., postscript or svg). Some imaging
760753
systems assume some value for pixels per inch::
761754
762755
points to pixels = points * pixels_per_inch/72.0 * dpi/72.0
756+
757+
Parameters
758+
----------
759+
points
760+
a float or a numpy array of float
761+
762+
Returns
763+
-------
764+
Points converted to pixels
763765
"""
764766
return points
765767

@@ -1211,11 +1213,11 @@ class TimerBase(object):
12111213
interval
12121214
The time between timer events in milliseconds. Default is 1000 ms.
12131215
1214-
single_shot: bool
1216+
single_shot : bool
12151217
Boolean flag indicating whether this timer should operate as single
12161218
shot (run once and then stop). Defaults to `False`.
12171219
1218-
callbacks: list
1220+
callbacks : list
12191221
Stores list of (func, args) tuples that will be called upon timer
12201222
events. This list can be manipulated directly, or the functions
12211223
`add_callback` and `remove_callback` can be used.
@@ -1541,8 +1543,9 @@ class MouseEvent(LocationEvent):
15411543
step
15421544
number of scroll steps (positive for 'up', negative for 'down')
15431545
1544-
1545-
Example usage::
1546+
Examples
1547+
--------
1548+
Usage::
15461549
15471550
def on_press(event):
15481551
print('you pressed', event.button, event.xdata, event.ydata)
@@ -1599,8 +1602,9 @@ class PickEvent(Event):
15991602
extra attributes than a
16001603
:class:`~matplotlib.collections.PatchCollection` pick event
16011604
1602-
1603-
Example usage::
1605+
Examples
1606+
--------
1607+
Usage::
16041608
16051609
ax.plot(np.rand(100), 'o', picker=5) # 5 points tolerance
16061610
@@ -1640,15 +1644,16 @@ class KeyEvent(LocationEvent):
16401644
combination of the above (e.g., "ctrl+alt+g", "ctrl+alt+G").
16411645
16421646
1643-
.. note::
1647+
Notes
1648+
-----
1649+
Modifier keys will be prefixed to the pressed key and will be in the order
1650+
"ctrl", "alt", "super". The exception to this rule is when the pressed key
1651+
is itself a modifier key, therefore "ctrl+alt" and "alt+control" can both
1652+
be valid key values.
16441653
1645-
Modifier keys will be prefixed to the pressed key and will be in the
1646-
order "ctrl", "alt", "super". The exception to this rule is when the
1647-
pressed key is itself a modifier key, therefore "ctrl+alt" and
1648-
"alt+control" can both be valid key values.
1649-
1650-
1651-
Example usage::
1654+
Examples
1655+
--------
1656+
Usage::
16521657
16531658
def on_key(event):
16541659
print('you pressed', event.key, event.xdata, event.ydata)
@@ -1891,6 +1896,9 @@ def button_release_event(self, x, y, button, guiEvent=None):
18911896
Backend derived classes should call this function on any mouse
18921897
button release.
18931898
1899+
This method will call all functions connected to the
1900+
'button_release_event' with a :class:`MouseEvent` instance.
1901+
18941902
Parameters
18951903
----------
18961904
x
@@ -1902,10 +1910,6 @@ def button_release_event(self, x, y, button, guiEvent=None):
19021910
guiEvent
19031911
the native UI event that generated the mpl event
19041912
1905-
1906-
This method will be call all functions connected to the
1907-
'button_release_event' with a :class:`MouseEvent` instance.
1908-
19091913
"""
19101914
s = 'button_release_event'
19111915
event = MouseEvent(s, self, x, y, button, self._key, guiEvent=guiEvent)
@@ -1917,6 +1921,9 @@ def motion_notify_event(self, x, y, guiEvent=None):
19171921
Backend derived classes should call this function on any
19181922
motion-notify-event.
19191923
1924+
This method will call all functions connected to the
1925+
'motion_notify_event' with a :class:`MouseEvent` instance.
1926+
19201927
Parameters
19211928
----------
19221929
x
@@ -1928,10 +1935,6 @@ def motion_notify_event(self, x, y, guiEvent=None):
19281935
guiEvent
19291936
the native UI event that generated the mpl event
19301937
1931-
1932-
This method will be call all functions connected to the
1933-
'motion_notify_event' with a :class:`MouseEvent` instance.
1934-
19351938
"""
19361939
self._lastx, self._lasty = x, y
19371940
s = 'motion_notify_event'
@@ -2078,8 +2081,8 @@ def print_figure(self, filename, dpi=None, facecolor=None, edgecolor=None,
20782081
face color background and you'll probably want to override this on
20792082
hardcopy.
20802083
2081-
Arguments
2082-
---------
2084+
Parameters
2085+
----------
20832086
filename
20842087
can also be a file object on image backends
20852088
@@ -2336,7 +2339,9 @@ def func(event)
23362339
Return value is a connection id that can be used with
23372340
:meth:`~matplotlib.backend_bases.Event.mpl_disconnect`.
23382341
2339-
Example usage::
2342+
Examples
2343+
--------
2344+
Usage::
23402345
23412346
def on_press(event):
23422347
print('you pressed', event.button, event.xdata, event.ydata)
@@ -2356,7 +2361,9 @@ def mpl_disconnect(self, cid):
23562361
"""
23572362
Disconnect callback id cid
23582363
2359-
Example usage::
2364+
Examples
2365+
--------
2366+
Usage::
23602367
23612368
cid = canvas.mpl_connect('button_press_event', on_press)
23622369
#...later
@@ -2371,13 +2378,13 @@ def new_timer(self, *args, **kwargs):
23712378
events through the backend's native event loop. Implemented only for
23722379
backends with GUIs.
23732380
2374-
Keyword Arguments
2375-
-----------------
2381+
Other Parameters
2382+
----------------
23762383
interval
2377-
Timer interval in milliseconds
2384+
Timer interval in milliseconds
23782385
callbacks
2379-
Sequence of (func, args, kwargs) where func(\*args, \*\*kwargs) will
2380-
be executed by the timer every *interval*.
2386+
Sequence of (func, args, kwargs) where ``func(*args, **kwargs)``
2387+
will be executed by the timer every *interval*.
23812388
23822389
"""
23832390
return TimerBase(*args, **kwargs)
@@ -3233,7 +3240,7 @@ class ToolContainerBase(object):
32333240
Attributes
32343241
----------
32353242
toolmanager : `ToolManager`
3236-
The tools that this `ToolContainer` wants to communicate with.
3243+
The tools with which this `ToolContainer` wants to communicate.
32373244
"""
32383245

32393246
def __init__(self, toolmanager):

‎lib/matplotlib/backends/backend_agg.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -577,21 +577,21 @@ def print_to_buffer(self):
577577
# add JPEG support
578578
def print_jpg(self, filename_or_obj, *args, **kwargs):
579579
"""
580-
Keyword Args
581-
------------
582-
quality: int
580+
Other Parameters
581+
----------------
582+
quality : int
583583
The image quality, on a scale from 1 (worst) to
584584
95 (best). The default is 95, if not given in the
585585
matplotlibrc file in the savefig.jpeg_quality parameter.
586586
Values above 95 should be avoided; 100 completely
587587
disables the JPEG quantization stage.
588588
589-
optimize: bool
589+
optimize : bool
590590
If present, indicates that the encoder should
591591
make an extra pass over the image in order to select
592592
optimal encoder settings.
593593
594-
progressive: bool
594+
progressive : bool
595595
If present, indicates that this image
596596
should be stored as a progressive JPEG file.
597597
"""

‎lib/matplotlib/backends/backend_gtk.py‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -108,12 +108,12 @@ class TimerGTK(TimerBase):
108108
109109
Attributes
110110
----------
111-
interval: int
111+
interval : int
112112
The time between timer events in milliseconds. Default is 1000 ms.
113-
single_shot: bool
113+
single_shot : bool
114114
Boolean flag indicating whether this timer should operate as single
115115
shot (run once and then stop). Defaults to False.
116-
callbacks: list
116+
callbacks : list
117117
Stores list of (func, args) tuples that will be called upon timer
118118
events. This list can be manipulated directly, or the functions
119119
`add_callback` and `remove_callback` can be used.
@@ -514,13 +514,13 @@ def new_timer(self, *args, **kwargs):
514514
This is useful for getting periodic events through the backend's native
515515
event loop. Implemented only for backends with GUIs.
516516
517-
Keyword Arguments
518-
-----------------
517+
Other Parameters
518+
----------------
519519
interval
520-
Timer interval in milliseconds
520+
Timer interval in milliseconds
521521
callbacks
522-
Sequence of (func, args, kwargs) where func(\*args, \*\*kwargs) will
523-
be executed by the timer every *interval*.
522+
Sequence of (func, args, kwargs) where ``func(*args, **kwargs)``
523+
will be executed by the timer every *interval*.
524524
"""
525525
return TimerGTK(*args, **kwargs)
526526

‎lib/matplotlib/backends/backend_gtk3.py‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -80,12 +80,12 @@ class TimerGTK3(TimerBase):
8080
8181
Attributes
8282
----------
83-
interval: int
83+
interval : int
8484
The time between timer events in milliseconds. Default is 1000 ms.
85-
single_shot: bool
85+
single_shot : bool
8686
Boolean flag indicating whether this timer should operate as single
8787
shot (run once and then stop). Defaults to False.
88-
callbacks: list
88+
callbacks : list
8989
Stores list of (func, args) tuples that will be called upon timer
9090
events. This list can be manipulated directly, or the functions
9191
`add_callback` and `remove_callback` can be used.
@@ -352,13 +352,13 @@ def new_timer(self, *args, **kwargs):
352352
This is useful for getting periodic events through the backend's native
353353
event loop. Implemented only for backends with GUIs.
354354
355-
Keyword Arguments
356-
-----------------
355+
Other Parameters
356+
----------------
357357
interval
358-
Timer interval in milliseconds
358+
Timer interval in milliseconds
359359
callbacks
360-
Sequence of (func, args, kwargs) where func(\*args, \*\*kwargs) will
361-
be executed by the timer every *interval*.
360+
Sequence of (func, args, kwargs) where ``func(*args, **kwargs)``
361+
will be executed by the timer every *interval*.
362362
"""
363363
return TimerGTK3(*args, **kwargs)
364364

‎lib/matplotlib/backends/backend_macosx.py‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -73,12 +73,12 @@ class TimerMac(_macosx.Timer, TimerBase):
7373
7474
Attributes
7575
----------
76-
interval: int
76+
interval : int
7777
The time between timer events in milliseconds. Default is 1000 ms.
78-
single_shot: bool
78+
single_shot : bool
7979
Boolean flag indicating whether this timer should operate as single
8080
shot (run once and then stop). Defaults to False.
81-
callbacks: list
81+
callbacks : list
8282
Stores list of (func, args) tuples that will be called upon timer
8383
events. This list can be manipulated directly, or the functions
8484
`add_callback` and `remove_callback` can be used.
@@ -92,16 +92,16 @@ class FigureCanvasMac(_macosx.FigureCanvas, FigureCanvasAgg):
9292
The canvas the figure renders into. Calls the draw and print fig
9393
methods, creates the renderers, etc...
9494
95+
Events such as button presses, mouse movements, and key presses
96+
are handled in the C code and the base class methods
97+
button_press_event, button_release_event, motion_notify_event,
98+
key_press_event, and key_release_event are called from there.
99+
95100
Attributes
96101
----------
97102
figure
98103
A Figure instance
99104
100-
101-
Events such as button presses, mouse movements, and key presses
102-
are handled in the C code and the base class methods
103-
button_press_event, button_release_event, motion_notify_event,
104-
key_press_event, and key_release_event are called from there.
105105
"""
106106

107107
def __init__(self, figure):
@@ -167,13 +167,13 @@ def new_timer(self, *args, **kwargs):
167167
This is useful for getting periodic events through the backend's native
168168
event loop. Implemented only for backends with GUIs.
169169
170-
Keyword Arguments
171-
-----------------
170+
Other Parameters
171+
----------------
172172
interval
173-
Timer interval in milliseconds
173+
Timer interval in milliseconds
174174
callbacks
175-
Sequence of (func, args, kwargs) where func(\*args, \*\*kwargs) will
176-
be executed by the timer every *interval*.
175+
Sequence of (func, args, kwargs) where ``func(*args, **kwargs)``
176+
will be executed by the timer every *interval*.
177177
"""
178178
return TimerMac(*args, **kwargs)
179179

0 commit comments

Comments
 (0)