Update docs for v0.8.0

README.rst

@@ -10,7 +10,7 @@ other contributors.
 Latest release
 ==============
 
-The latest release is **v0.7.0 beta 2** released on 9th October 2015.
+The latest release is **v0.8.0 beta 3** released on 16th October 2015.
 
 About
 =====
@@ -33,6 +33,10 @@ colour LEDs, robotics kits and more.
 Install
 =======
 
+First, install the dependencies::
+
+    sudo apt-get install python-pip python3-pip python-w1thermsensor python3-w1thermsensor python-spidev python3-spidev
+
 Install with pip::
 
     sudo pip install gpiozero

docs/boards.md

@@ -264,10 +264,10 @@ Create a `RyanteckRobot` object:
 robot = RyanteckRobot()
 ```
 
+The interface is identical to the generic `Robot` interface.
+
 There's no need to configure the pins if you're using the default pins
 `(17, 18)` for the left motor and `(22, 23)` for the right motor.
 
-The interface is identical to the generic `Robot` interface.
-
 To use the Ryanteck MCB on another set of pins, just use the generic `Robot`
 interface.

docs/inputs.md

@@ -89,11 +89,19 @@ pir = MotionSensor(4)
 
 ### Methods
 
-...
+| Method | Description | Arguments |
+| ------ | ----------- | --------- |
+| `wait_for_motion()`    | Halt the program until motion is detected.    | `timeout` - The number of seconds to wait before proceeding if no motion is detected. Default: `None`    |
+| `wait_for_no_motion()` | Halt the program until no motion is detected. | `timeout` - The number of seconds to wait before proceeding if motion is still detected. Default: `None` |
 
 ### Properties
 
-...
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| `pin`    | The GPIO pin number the sensor is connected to. | Integer |
+| `motion_detected` | The current state of the sensor (`True` if motion is detected; otherwise `False`). | Boolean |
+| `when_motion` | A reference to the function to be called when motion is detected. | None or Function |
+| `when_no_motion` | A reference to the function to be called when no motion is detected. | None or Function |
 
 ## Light Sensor
 
@@ -120,15 +128,23 @@ light = LightSensor(4)
 
 ### Methods
 
-...
+| Method | Description | Arguments |
+| ------ | ----------- | --------- |
+| `wait_for_light()` | Halt the program until light is detected.    | `timeout` - The number of seconds to wait before proceeding if light is not detected. Default: `None` |
+| `wait_for_dark()`  | Halt the program until darkness is detected. | `timeout` - The number of seconds to wait before proceeding if darkness is not detected. Default: `None` |
 
 ### Properties
 
-...
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| `pin`            | The GPIO pin number the sensor is connected to.                       | Integer          |
+| `light_detected` | The current state of the sensor (`True` if light; otherwise `False`). | Boolean          |
+| `when_light`     | A reference to the function to be called when light is detected.      | None or Function |
+| `when_dark`      | A reference to the function to be called when darkness is detected.   | None or Function |
 
 ## Temperature Sensor
 
-Digital Temperature Sensor.
+One-wire Digital Temperature Sensor.
 
 ### Wiring
 
@@ -148,14 +164,16 @@ Create a `TemperatureSensor` object:
 temp = TemperatureSensor()
 ```
 
-### Properties
-
-...
-
 ### Methods
 
 ...
 
+### Properties
+
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| `value`  | The current temperature reading in degrees Celsius. | Float |
+
 ## MCP3008 Analogue-to-Digital Converter
 
 MCP3008 ADC (Analogue-to-Digital converter).
@@ -175,18 +193,38 @@ Ensure the `MCP3008` class is imported at the top of the file:
 from gpiozero import MCP3008
 ```
 
-Access an input value with the `MCP3008`'s context manager:
+Create an `MCP3008` object:
+
+```python
+pot = MCP3008()
+```
+
+Read the value of the device:
+
+```python
+print(pot.value)
+```
+
+Alternatively, access an input value with the `MCP3008`'s context manager:
 
 ```python
 with MCP3008() as pot:
-    print(pot.read())
+    print(pot.value)
 ```
 
-It is possible to specify the `bus`, the `device` and the `channel` you wish to
+It is possible to specify the `device` and the `channel` you wish to access.
-access. The previous example used the default value of `0` for each of these.
+The previous example used the default value of `0` for each of these. To
-To specify them, pass them in as arguments:
+specify them, pass them in as arguments:
 
 ```python
-with MCP3008(bus=1, device=1, channel=4) as pot:
+pot = MCP3008(device=1, channel=7)
-    print(pot.read())
 ```
+
+## MCP3004 Analogue-to-Digital Converter
+
+MCP3004 ADC (Analogue-to-Digital converter).
+
+The MCP3004 chip provides access to up to 4 analogue inputs, such as
+potentiometers, and read their values in digital form.
+
+The interface is identical to `MCP3008`.

docs/notes.md

@@ -78,7 +78,163 @@ devices, the program needs to be running for the events to be detected:
 from gpiozero import Button
 from signal import pause
 
+def hello():
+    print("Hello")
+
 button = Button(2)
-button.when_pressed = lambda: print("Button was pressed!")
+button.when_pressed = hello
 pause()
 ```
+
+## Importing from GPIO Zero
+
+In Python, libraries and functions used in a script must be imported by name at
+the top of the file, with the exception of the functions built in to Python by
+default.
+
+For example, to use the `Button` interface from the GPIO Zero library, it
+should be explicitly imported:
+
+```python
+from gpiozero import Button
+```
+
+Now `Button` is available directly in the script:
+
+```python
+button = Button(2)
+```
+
+Alternatively, the whole GPIO Zero library can be imported:
+
+```python
+import gpiozero
+```
+
+In this case, all references to interfaces within GPIO Zero must be prefixed:
+
+```python
+button = gpiozero.Button(2)
+```
+
+## Programming terms
+
+The following terms are used in the documentation.
+
+### Class
+
+A class is the blueprint for a data type. A class defines the way an instance
+of its own can behave, and has specific functionality relating to the kinds of
+things a user would expect to be able to do with it.
+
+An example of a class in GPIO Zero is `Button`. Note class names are given with
+each word capitalised.
+
+### Object
+
+An object is an instance of a class. Any variable in Python is an object of a
+given type (e.g. Integer, String, Float), and comprises the functionality
+defined by its class.
+
+To create an object, you must assign a variable name to an instance of a class:
+
+```python
+my_button = Button(2)
+```
+
+Now the variable `my_button` is an instance of the class `Button`. Check its
+type with Python's `type()` function:
+
+```python
+print(type(my_button))
+```
+
+which shows:
+
+```
+gpiozero.Button
+```
+
+Most classes in GPIO Zero require some parameters to create an object, for
+example the `LED` and `Button` examples require the pin number the device is
+attached to. Some classes require no parameters, others require multiple
+parameters, usually with some being optional. When parameters are optional,
+common default values are used.
+
+### Method
+
+A method is a function defined within a class. With an object of a given type,
+you can call a method on that object. For example if `my_led` is a `LED`
+object:
+
+```python
+my_led.on()
+```
+
+will call the `LED` class's `on()` function, relating to that instance of
+`LED`. If other `LED` objects have been created, they will not be affected by
+this action.
+
+In many cases, no parameters are required to call the method (like
+`my_led.on()`). In other cases, optional parameters are available. For example:
+
+```python
+my_led.blink(2, 3)
+```
+
+Here, the parameters `2` and `3` have been passed in as parameters. The `blink`
+method allows configuration of `on_time` and `off_time`. This example means the
+LED will flash on for 2 seconds and stay off for 3.
+
+Parameters can also be passed in by name, which means order is irrelevant. For
+example:
+
+```python
+my_led.blink(off_time=3)
+```
+
+Here, only the `off_time` parameter has been provided, and all other parameters
+will use their default values. Methods in GPIO Zero use sensible common default
+values, but are configurable.
+
+### Property
+
+A property is an attribute relating to the state of an object. For example:
+
+```python
+my_led.is_active
+```
+
+This will return `True` or `False` depending on whether or not the LED is
+currently on.
+
+Some properties allow you to change their value. For example an `RGBLED` object:
+
+```python
+rgb_led.green = 0.5
+```
+
+or:
+
+```python
+rgb_led.color = (0.2, 0.3, 0.7)
+```
+
+### Context manager
+
+A context manager is an alternative interface provided by classes which require
+"closing" the object when it's finished with. The following example (using a
+context manager):
+
+```python
+with MCP3008() as pot:
+    print(pot.value)
+```
+
+is identical to:
+
+```python
+pot = MCP3008()
+print(pot.value)
+pot.close()
+```

docs/outputs.md

@@ -53,7 +53,7 @@ led = LED(17)
 | Property | Description | Type |
 | -------- | ----------- | ---- |
 | `pin`    | The GPIO pin number the LED is connected to. | Integer |
-| `is_active` | The current state of the pin (`True` if on; `False` if off). | Boolean |
+| `is_active` | The current state of the LED (`True` if on; `False` if off). | Boolean |
 
 ## Buzzer
 
@@ -98,7 +98,7 @@ buzzer = Buzzer(3)
 | Property | Description | Type |
 | -------- | ----------- | ---- |
 | `pin`       | The GPIO pin number the buzzer is connected to.                 | Integer |
-| `is_active` | The current state of the pin (`True` if on; `False` if off). | Boolean |
+| `is_active` | The current state of the buzzer (`True` if on; `False` if off). | Boolean |
 
 ## RGB LED
 
@@ -139,15 +139,19 @@ led = RGBLED(2, 3, 4)
 | `on()`     | Turn all the LEDs on (makes white light). | None |
 | `off()`    | Turn all the LEDs off.                    | None |
 | `toggle()` | Toggle the LED. If it's on (at all), turn it off; if it's off, turn it on. | None |
+| `blink()`  | Make the LED turn on and off repeatedly. | `on_time` - The amount of time (in seconds) for the LED to be on each iteration. Default: `1` |
+|            |                                          | `off_time` - The amount of time (in seconds) for the LED to be off each iteration. Default: `1` |
+|            |                                          | `n` - The number of iterations. `None` means infinite. Default: `None` |
+|            |                                          | `background` - If True, start a background thread to continue blinking and return immediately. If False, only return when the blink is finished (warning: the default value of n will result in this method never returning). Default: `True` |
 
 ### Properties
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
-| `red`    | The brightness value of the red LED (0 to 255).     | Integer |
+| `red`    | The brightness value of the red LED (0 to 1).     | Integer |
-| `green`  | The brightness value of the green LED (0 to 255).   | Integer |
+| `green`  | The brightness value of the green LED (0 to 1).   | Integer |
-| `blue`   | The brightness value of the blue LED (0 to 255).    | Integer |
+| `blue`   | The brightness value of the blue LED (0 to 1).    | Integer |
-| `rgb`    | The brightness values of the three LEDs (0 to 255). | Tuple   |
+| `color`  | The brightness values of the three LEDs (0 to 1). | Tuple   |
 
 ## Motor
 

gpiozero/input_devices.py

@@ -576,5 +576,3 @@ class MCP3004(MCP3008):
         # channel number must be 0 (effectively restricting it to 4 channels)
         if not 0 <= channel < 4:
             raise InputDeviceError('channel must be between 0 and 3')
-
-

gpiozero/output_devices.py

@@ -224,7 +224,8 @@ class PWMOutputDevice(DigitalOutputDevice):
     value = property(_get_value, _set_value, doc="""\
         The duty cycle of the PWM device. 0.0 is off, 1.0 is fully on. Values
         in between may be specified for varying levels of power in the device.
-        """)
+        """
+    )
 
     @property
     def is_active(self):
@@ -240,7 +241,8 @@ class PWMOutputDevice(DigitalOutputDevice):
     frequency = property(_get_frequency, _set_frequency, doc="""\
         The frequency of the pulses used with the PWM device, in Hz. The
         default is 100.
-        """)
+        """
+    )
 
 
 def _led_property(index, doc=None):