Skip to content

Commit c4cbe75

Browse files
dwalton76dwalton76
authored
use double backticks consistently in docstrings (#710)
1 parent 72c9292 commit c4cbe75

13 files changed

Lines changed: 206 additions & 212 deletions

File tree

‎debian/changelog‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ python-ev3dev2 (2.1.0) UNRELEASED; urgency=medium
22

33
[Daniel Walton]
44
* RPyC update docs and make it easier to use
5+
* use double backticks consistently in docstrings
56

67
[Matěj Volf]
78
* LED animation fix duration None

‎ev3dev2/button.py‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -71,8 +71,8 @@ def __str__(self):
7171
@staticmethod
7272
def on_change(changed_buttons):
7373
"""
74-
This handler is called by `process()` whenever state of any button has
75-
changed since last `process()` call. `changed_buttons` is a list of
74+
This handler is called by ``process()`` whenever state of any button has
75+
changed since last ``process()`` call. ``changed_buttons`` is a list of
7676
tuples of changed button names and their states.
7777
"""
7878
pass
@@ -89,7 +89,7 @@ def any(self):
8989

9090
def check_buttons(self, buttons=[]):
9191
"""
92-
Check if currently pressed buttons exactly match the given list.
92+
Check if currently pressed buttons exactly match the given list ``buttons``.
9393
"""
9494
return set(self.buttons_pressed) == set(buttons)
9595

@@ -98,20 +98,20 @@ def _wait(self, wait_for_button_press, wait_for_button_release, timeout_ms):
9898

9999
def wait_for_pressed(self, buttons, timeout_ms=None):
100100
"""
101-
Wait for the button to be pressed down.
101+
Wait for ``buttons`` to be pressed down.
102102
"""
103103
return self._wait(buttons, [], timeout_ms)
104104

105105
def wait_for_released(self, buttons, timeout_ms=None):
106106
"""
107-
Wait for the button to be released.
107+
Wait for ``buttons`` to be released.
108108
"""
109109
return self._wait([], buttons, timeout_ms)
110110

111111
def wait_for_bump(self, buttons, timeout_ms=None):
112112
"""
113-
Wait for the button to be pressed down and then released.
114-
Both actions must happen within timeout_ms.
113+
Wait for ``buttons`` to be pressed down and then released.
114+
Both actions must happen within ``timeout_ms``.
115115
"""
116116
stopwatch = StopWatch()
117117
stopwatch.start()
@@ -125,7 +125,7 @@ def wait_for_bump(self, buttons, timeout_ms=None):
125125

126126
def process(self, new_state=None):
127127
"""
128-
Check for currenly pressed buttons. If the new state differs from the
128+
Check for currenly pressed buttons. If the ``new_state`` differs from the
129129
old state, call the appropriate button event handlers (on_up, on_down, etc).
130130
"""
131131
if new_state is None:
@@ -146,9 +146,9 @@ def process(self, new_state=None):
146146

147147
class EV3ButtonCommon(object):
148148

149-
# These handlers are called by `ButtonCommon.process()` whenever the
149+
# These handlers are called by ButtonCommon.process() whenever the
150150
# state of 'up', 'down', etc buttons have changed since last
151-
# `ButtonCommon.process()` call
151+
# ButtonCommon.process() call
152152
on_up = None
153153
on_down = None
154154
on_left = None
@@ -159,42 +159,42 @@ class EV3ButtonCommon(object):
159159
@property
160160
def up(self):
161161
"""
162-
Check if 'up' button is pressed.
162+
Check if ``up`` button is pressed.
163163
"""
164164
return 'up' in self.buttons_pressed
165165

166166
@property
167167
def down(self):
168168
"""
169-
Check if 'down' button is pressed.
169+
Check if ``down`` button is pressed.
170170
"""
171171
return 'down' in self.buttons_pressed
172172

173173
@property
174174
def left(self):
175175
"""
176-
Check if 'left' button is pressed.
176+
Check if ``left`` button is pressed.
177177
"""
178178
return 'left' in self.buttons_pressed
179179

180180
@property
181181
def right(self):
182182
"""
183-
Check if 'right' button is pressed.
183+
Check if ``right`` button is pressed.
184184
"""
185185
return 'right' in self.buttons_pressed
186186

187187
@property
188188
def enter(self):
189189
"""
190-
Check if 'enter' button is pressed.
190+
Check if ``enter`` button is pressed.
191191
"""
192192
return 'enter' in self.buttons_pressed
193193

194194
@property
195195
def backspace(self):
196196
"""
197-
Check if 'backspace' button is pressed.
197+
Check if ``backspace`` button is pressed.
198198
"""
199199
return 'backspace' in self.buttons_pressed
200200

‎ev3dev2/console.py‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ def __init__(self, font="Lat15-TerminusBold24x12"):
3434

3535
Parameter:
3636

37-
- `font` (string): Font name, as found in `/usr/share/consolefonts/`
37+
- ``font`` (string): Font name, as found in ``/usr/share/consolefonts/``
3838

3939
"""
4040
self._font = None
@@ -94,38 +94,38 @@ def cursor(self, value):
9494

9595
def text_at(self, text, column=1, row=1, reset_console=False, inverse=False, alignment="L"):
9696
"""
97-
Display `text` (string) at grid position (`column`, `row`).
97+
Display ``text`` (string) at grid position (``column``, ``row``).
9898
Note that the grid locations are 1-based (not 0-based).
9999

100100
Depending on the font, the number of columns and rows supported by the EV3 LCD console
101101
can vary. Large fonts support as few as 11 columns and 4 rows, while small fonts support
102102
44 columns and 21 rows. The default font for the Console() class results in a grid that
103103
is 14 columns and 5 rows.
104104

105-
Using the `inverse=True` parameter will display the `text` with more emphasis and contrast,
105+
Using the ``inverse=True`` parameter will display the ``text`` with more emphasis and contrast,
106106
as the background of the text will be black, and the foreground is white. Using inverse
107107
can help in certain situations, such as to indicate when a color sensor senses
108108
black, or the gyro sensor is pointing to zero.
109109

110-
Use the `alignment` parameter to enable the function to align the `text` differently to the
111-
column/row values passed-in. Use `L` for left-alignment (default), where the first character
112-
in the `text` will show at the column/row position. Use `R` for right-alignment, where the
113-
last character will show at the column/row position. Use `C` for center-alignment, where the
110+
Use the ``alignment`` parameter to enable the function to align the ``text`` differently to the
111+
column/row values passed-in. Use ``L`` for left-alignment (default), where the first character
112+
in the ``text`` will show at the column/row position. Use ``R`` for right-alignment, where the
113+
last character will show at the column/row position. Use ``C`` for center-alignment, where the
114114
text string will centered at the column/row position (as close as possible using integer
115115
division--odd-length text string will center better than even-length).
116116

117117
Parameters:
118118

119-
- `text` (string): Text to display
120-
- `column` (int): LCD column position to start the text (1 = left column);
119+
- ``text`` (string): Text to display
120+
- ``column`` (int): LCD column position to start the text (1 = left column);
121121
text will wrap when it reaches the right edge
122-
- `row` (int): LCD row position to start the text (1 = top row)
123-
- `reset_console` (bool): ``True`` to reset the EV3 LCD console before showing
122+
- ``row`` (int): LCD row position to start the text (1 = top row)
123+
- ``reset_console`` (bool): ``True`` to reset the EV3 LCD console before showing
124124
the text; default is ``False``
125-
- `inverse` (bool): ``True`` for white on black, otherwise black on white;
125+
- ``inverse`` (bool): ``True`` for white on black, otherwise black on white;
126126
default is ``False``
127-
- `alignment` (string): Align the `text` horizontally. Use `L` for left-alignment (default),
128-
`R` for right-alignment, or `C` for center-alignment
127+
- ``alignment`` (string): Align the ``text`` horizontally. Use ``L`` for left-alignment (default),
128+
``R`` for right-alignment, or ``C`` for center-alignment
129129

130130
"""
131131

@@ -149,8 +149,8 @@ def set_font(self, font="Lat15-TerminusBold24x12", reset_console=True):
149149

150150
Parameters:
151151

152-
- `font` (string): Font name, as found in `/usr/share/consolefonts/`
153-
- `reset_console` (bool): ``True`` to reset the EV3 LCD console
152+
- ``font`` (string): Font name, as found in ``/usr/share/consolefonts/``
153+
- ``reset_console`` (bool): ``True`` to reset the EV3 LCD console
154154
after the font change; default is ``True``
155155

156156
"""
@@ -166,13 +166,13 @@ def set_font(self, font="Lat15-TerminusBold24x12", reset_console=True):
166166

167167
def clear_to_eol(self, column=None, row=None):
168168
"""
169-
Clear to the end of line from the `column` and `row` position
169+
Clear to the end of line from the ``column`` and ``row`` position
170170
on the EV3 LCD console. Default to current cursor position.
171171

172172
Parameters:
173173

174-
- `column` (int): LCD column position to move to before clearing
175-
- `row` (int): LCD row position to move to before clearing
174+
- ``column`` (int): LCD column position to move to before clearing
175+
- ``row`` (int): LCD row position to move to before clearing
176176

177177
"""
178178
if column is not None and row is not None:

‎ev3dev2/display.py‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -157,9 +157,8 @@ def __init__(self, fbdev=None):
157157
def _open_fbdev(fbdev=None):
158158
"""Return the framebuffer file descriptor.
159159

160-
Try to use the FRAMEBUFFER
161-
environment variable if fbdev is not given. Use '/dev/fb0' by
162-
default.
160+
Try to use the FRAMEBUFFER environment variable if fbdev is
161+
not given. Use '/dev/fb0' by default.
163162
"""
164163
dev = fbdev or os.getenv('FRAMEBUFFER', '/dev/fb0')
165164
fbfid = os.open(dev, os.O_RDWR)
@@ -370,19 +369,19 @@ def point(self, clear_screen=True, x=10, y=10, point_color='black'):
370369

371370
def text_pixels(self, text, clear_screen=True, x=0, y=0, text_color='black', font=None):
372371
"""
373-
Display `text` starting at pixel (x, y).
372+
Display ``text`` starting at pixel (x, y).
374373

375374
The EV3 display is 178x128 pixels
376375

377376
- (0, 0) would be the top left corner of the display
378377
- (89, 64) would be right in the middle of the display
379378

380-
'text_color' : PIL says it supports "common HTML color names". There
379+
``text_color`` : PIL says it supports "common HTML color names". There
381380
are 140 HTML color names listed here that are supported by all modern
382381
browsers. This is probably a good list to start with.
383382
https://www.w3schools.com/colors/colors_names.asp
384383

385-
'font' : can be any font displayed here
384+
``font`` : can be any font displayed here
386385
http://ev3dev-lang.readthedocs.io/projects/python-ev3dev/en/ev3dev-stretch/display.html#bitmap-fonts
387386

388387
- If font is a string, it is the name of a font to be loaded.
@@ -404,18 +403,18 @@ def text_pixels(self, text, clear_screen=True, x=0, y=0, text_color='black', fon
404403

405404
def text_grid(self, text, clear_screen=True, x=0, y=0, text_color='black', font=None):
406405
"""
407-
Display 'text' starting at grid (x, y)
406+
Display ``text`` starting at grid (x, y)
408407

409408
The EV3 display can be broken down in a grid that is 22 columns wide
410409
and 12 rows tall. Each column is 8 pixels wide and each row is 10
411410
pixels tall.
412411

413-
'text_color' : PIL says it supports "common HTML color names". There
412+
``text_color`` : PIL says it supports "common HTML color names". There
414413
are 140 HTML color names listed here that are supported by all modern
415414
browsers. This is probably a good list to start with.
416415
https://www.w3schools.com/colors/colors_names.asp
417416

418-
'font' : can be any font displayed here
417+
``font`` : can be any font displayed here
419418
http://ev3dev-lang.readthedocs.io/projects/python-ev3dev/en/ev3dev-stretch/display.html#bitmap-fonts
420419

421420
- If font is a string, it is the name of a font to be loaded.

‎ev3dev2/led.py‎

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ def max_brightness(self):
110110
@property
111111
def brightness(self):
112112
"""
113-
Sets the brightness level. Possible values are from 0 to `max_brightness`.
113+
Sets the brightness level. Possible values are from 0 to ``max_brightness``.
114114
"""
115115
self._brightness, value = self.get_attr_int(self._brightness, 'brightness')
116116
return value
@@ -133,17 +133,17 @@ def trigger(self):
133133
Sets the LED trigger. A trigger is a kernel based source of LED events.
134134
Triggers can either be simple or complex. A simple trigger isn't
135135
configurable and is designed to slot into existing subsystems with
136-
minimal additional code. Examples are the `ide-disk` and `nand-disk`
136+
minimal additional code. Examples are the ``ide-disk`` and ``nand-disk``
137137
triggers.
138138

139139
Complex triggers whilst available to all LEDs have LED specific
140-
parameters and work on a per LED basis. The `timer` trigger is an example.
141-
The `timer` trigger will periodically change the LED brightness between
142-
0 and the current brightness setting. The `on` and `off` time can
143-
be specified via `delay_{on,off}` attributes in milliseconds.
140+
parameters and work on a per LED basis. The ``timer`` trigger is an example.
141+
The ``timer`` trigger will periodically change the LED brightness between
142+
0 and the current brightness setting. The ``on`` and ``off`` time can
143+
be specified via ``delay_{on,off}`` attributes in milliseconds.
144144
You can change the brightness value of a LED independently of the timer
145145
trigger. However, if you set the brightness value to 0 it will
146-
also disable the `timer` trigger.
146+
also disable the ``timer`` trigger.
147147
"""
148148
self._trigger, value = self.get_attr_from_set(self._trigger, 'trigger')
149149
return value
@@ -179,9 +179,9 @@ def trigger(self, value):
179179
@property
180180
def delay_on(self):
181181
"""
182-
The `timer` trigger will periodically change the LED brightness between
183-
0 and the current brightness setting. The `on` time can
184-
be specified via `delay_on` attribute in milliseconds.
182+
The ``timer`` trigger will periodically change the LED brightness between
183+
0 and the current brightness setting. The ``on`` time can
184+
be specified via ``delay_on`` attribute in milliseconds.
185185
"""
186186

187187
# Workaround for ev3dev/ev3dev#225.
@@ -219,9 +219,9 @@ def delay_on(self, value):
219219
@property
220220
def delay_off(self):
221221
"""
222-
The `timer` trigger will periodically change the LED brightness between
223-
0 and the current brightness setting. The `off` time can
224-
be specified via `delay_off` attribute in milliseconds.
222+
The ``timer`` trigger will periodically change the LED brightness between
223+
0 and the current brightness setting. The ``off`` time can
224+
be specified via ``delay_off`` attribute in milliseconds.
225225
"""
226226

227227
# Workaround for ev3dev/ev3dev#225.
@@ -241,11 +241,13 @@ def delay_off(self):
241241

242242
@delay_off.setter
243243
def delay_off(self, value):
244-
# Workaround for ev3dev/ev3dev#225.
245-
# 'delay_on' and 'delay_off' attributes are created when trigger is set
246-
# to 'timer', and destroyed when it is set to anything else.
247-
# This means the file cache may become outdated, and we may have to
248-
# reopen the file.
244+
"""
245+
Workaround for ev3dev/ev3dev#225.
246+
``delay_on`` and ``delay_off`` attributes are created when trigger is set
247+
to ``timer``, and destroyed when it is set to anything else.
248+
This means the file cache may become outdated, and we may have to
249+
reopen the file.
250+
"""
249251
for retry in (True, False):
250252
try:
251253
self._delay_off = self.set_attr_int(self._delay_off, 'delay_off', value)

0 commit comments

Comments
 (0)