Add documentation for Motor, Robot and RyanteckRobot

docs/boards.md

@@ -8,6 +8,8 @@ These additional interfaces have been provided to group collections of component
 
 A Generic LED Board or collection of LEDs.
 
+### Code
+
 Ensure the `LEDBoard` class is imported at the top of the file:
 
 ```python
@@ -39,6 +41,8 @@ leds = LEDBoard([2, 3, 4, 5, 6])
 
 Generic Traffic Lights set.
 
+### Code
+
 Ensure the `TrafficLights` class is imported at the top of the file:
 
 ```python
@@ -79,6 +83,8 @@ traffic = TrafficLights(2, 3, 4)
 
 Ciseco Pi-LITEr: strip of 8 very bright LEDs.
 
+### Code
+
 Ensure the `PiLiter` class is imported at the top of the file:
 
 ```python
@@ -148,6 +154,8 @@ To use the PI-TRAFFIC board on another set of pins, just use the generic `Traffi
 
 Pi Supply Fish Dish: traffic light LEDs, a button and a buzzer.
 
+### Code
+
 Ensure the `FishDish` class is imported at the top of the file:
 
 ```python
@@ -189,6 +197,8 @@ fish = FishDish()
 
 Ryanteck Traffic HAT: traffic light LEDs, a button and a buzzer.
 
+### Code
+
 Ensure the `TrafficHat` class is imported at the top of the file:
 
 ```python
@@ -225,3 +235,43 @@ traffic = TrafficHat()
 | `button` | Direct access to the button as a single `Button` object. | LED |
 | `leds`   | A collection of LEDs to access each one individually, or to iterate over them in sequence. | Tuple |
 | `all`    | A collection of the board's output components to access each one individually, or to iterate over them in sequence. | Tuple |
+
+## Traffic HAT
+
+Ryanteck Traffic HAT: traffic light LEDs, a button and a buzzer.
+
+### Code
+
+Ensure the `Robot` class is imported at the top of the file:
+
+```python
+from gpiozero import Robot
+```
+
+Create a `Robot` object by passing in the pin numbers of the forward and back pairs for each motor:
+
+```python
+robot = Robot(left=(4, 14), right=(17, 18))
+```
+
+### Methods
+
+| Method | Description | Arguments |
+| ------ | ----------- | --------- |
+| `forward()` | Drive the robot forwards. | `seconds` - The number of seconds to drive for. If `None`, stay on. Default: `None` |
+| `backward()` | Drive the robot backwards. | `seconds` - The number of seconds to drive for. If `None`, stay on. Default: `None` |
+| `left()` | Make the robot turn left. | `seconds` - The number of seconds to turn for. If `None`, stay on. Default: `None` |
+| `right()` | Make the robot turn right. | `seconds` - The number of seconds to turn for. If `None`, stay on. Default: `None` |
+| `stop()` | Stop the robot. | None |
+
+## Ryanteck MCB Robot
+
+Generic robot controller with pre-configured pin numbers.
+
+Same interface as generic `Robot` class, without the need to configure pins:
+
+```python
+from gpiozero import RyanteckRobot
+
+robot = RyanteckRobot()
+```

docs/outputs.md

@@ -149,22 +149,16 @@ Ensure the `Motor` class is imported at the top of the file:
 from gpiozero import Motor
 ```
 
-Create a `Motor` object by passing in the pin number the motor is connected to:
+Create a `Motor` object by passing in the pin numbers the motor is connected to:
 
 ```python
-motor = Motor(4)
+motor = Motor(forward=17, back=18)
 ```
 
 ### Methods
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |
-| `on()` | Turn the motor on. | None |
+| `forward()` | Drive the motor forwards. | `seconds` - The number of seconds to stay on for. If `None`, stay on. Default: `None` |
-| `off()` | Turn the motor off. | None |
+| `backward()` | Drive the motor backwards. | `seconds` - The number of seconds to stay on for. If `None`, stay on. Default: `None` |
-
+| `stop()` | Stop the motor. | None |
-### Properties
-
-| Property | Description | Type |
-| -------- | ----------- | ---- |
-| `pin`    | The GPIO pin number the motor is connected to. | Integer |
-| `is_active` | The current state of the pin (`True` if on; `False` if off). | Boolean |

gpiozero/boards.py

@@ -231,7 +231,8 @@ class Robot(object):
 
     def left(self, seconds=None):
         """
-        Turn left. If seconds given, stop after given number of seconds.
+        Make the robot turn left. If seconds given, stop after given number of
+        seconds.
 
         seconds: None
             Number of seconds to turn left for
@@ -245,7 +246,8 @@ class Robot(object):
 
     def right(self, seconds=None):
         """
-        Turn right. If seconds given, stop after given number of seconds.
+        Make the robot turn right. If seconds given, stop after given number of
+        seconds.
 
         seconds: None
             Number of seconds to turn right for
@@ -259,7 +261,7 @@ class Robot(object):
 
     def forward(self, seconds=None):
         """
-        Drive forward. If seconds given, stop after given number of seconds.
+        Drive the robot forward. If seconds given, stop after given number of seconds.
 
         seconds: None
             Number of seconds to drive forward for
@@ -273,7 +275,7 @@ class Robot(object):
 
     def backward(self, seconds=None):
         """
-        Drive backward. If seconds given, stop after given number of seconds.
+        Drive the robot backward. If seconds given, stop after given number of seconds.
 
         seconds: None
             Number of seconds to drive backward for
@@ -287,13 +289,16 @@ class Robot(object):
 
     def stop(self):
         """
-        Stop both motors.
+        Stop the robot.
         """
         self._left.stop()
         self._right.stop()
 
 
 class RyanteckRobot(Robot):
+    """
+    RTK MCB Robot. Generic robot controller with pre-configured pin numbers.
+    """
     def __init__(self):
         left = (17, 18)
         right = (22, 23)

gpiozero/output_devices.py

@@ -256,14 +256,14 @@ class Motor(object):
 
     def forward(self):
         """
-        Turn the motor on, forwards
+        Drive the motor forwards
         """
         self._forward.on()
         self._backward.off()
 
     def backward(self):
         """
-        Turn the motor on, backwards
+        Drive the motor backwards
         """
         self._backward.on()
         self._forward.off()