Restructure index

Move the API to the end, recipes all grouped together up-front (with
remote GPIO setup just before the remote GPIO recipes). Tweak some
headings so everything looks a little more consistent in the (now
shorter) ToC.

Also added module index tags.

docs/api_boards.rst

@@ -1,6 +1,8 @@
-======================
+============================
-Boards and Accessories
+API - Boards and Accessories
-======================
+============================
+
+.. module:: gpiozero.boards
 
 .. currentmodule:: gpiozero
 

docs/api_exc.rst

@@ -1,6 +1,6 @@
-==========
+================
-Exceptions
+API - Exceptions
-==========
+================
 
 .. currentmodule:: gpiozero
 

docs/api_generic.rst

@@ -1,6 +1,8 @@
-===============
+=====================
-Generic Classes
+API - Generic Classes
-===============
+=====================
+
+.. module:: gpiozero.devices
 
 .. currentmodule:: gpiozero
 

docs/api_info.rst

@@ -0,0 +1,20 @@
+====================
+API - Pi Information
+====================
+
+.. currentmodule:: gpiozero
+
+The GPIO Zero library also contains a database of information about the various
+revisions of the Raspberry Pi computer. This is used internally to raise
+warnings when non-physical pins are used, or to raise exceptions when
+pull-downs are requested on pins with physical pull-up resistors attached. The
+following functions and classes can be used to query this database:
+
+.. autofunction:: pi_info
+
+.. autoclass:: PiBoardInfo
+
+.. autoclass:: HeaderInfo
+
+.. autoclass:: PinInfo
+

docs/api_input.rst

@@ -1,6 +1,8 @@
-=============
+===================
-Input Devices
+API - Input Devices
-=============
+===================
+
+.. module:: gpiozero.input_devices
 
 .. currentmodule:: gpiozero
 

docs/api_other.rst

@@ -1,6 +1,8 @@
-================
+======================
-Internal Devices
+API - Internal Devices
-================
+======================
+
+.. module:: gpiozero.other_devices
 
 .. currentmodule:: gpiozero
 

docs/api_output.rst

@@ -1,6 +1,8 @@
-==============
+====================
-Output Devices
+API - Output Devices
-==============
+====================
+
+.. module:: gpiozero.output_devices
 
 .. currentmodule:: gpiozero
 

docs/api_pins.rst

@@ -1,6 +1,8 @@
-====
+==========
-Pins
+API - Pins
-====
+==========
+
+.. module:: gpiozero.pins
 
 .. currentmodule:: gpiozero
 
@@ -165,7 +167,7 @@ Base classes
 .. autoclass:: SPI
     :members:
 
-.. currentmodule:: gpiozero.pins.pi
+.. module:: gpiozero.pins.pi
 
 .. autoclass:: PiFactory
     :members:
@@ -173,7 +175,7 @@ Base classes
 .. autoclass:: PiPin
     :members:
 
-.. currentmodule:: gpiozero.pins.local
+.. module:: gpiozero.pins.local
 
 .. autoclass:: LocalPiFactory
     :members:
@@ -185,7 +187,7 @@ Base classes
 RPi.GPIO
 ========
 
-.. currentmodule:: gpiozero.pins.rpigpio
+.. module:: gpiozero.pins.rpigpio
 
 .. autoclass:: gpiozero.pins.rpigpio.RPiGPIOFactory
 
@@ -195,7 +197,7 @@ RPi.GPIO
 RPIO
 ====
 
-.. currentmodule:: gpiozero.pins.rpio
+.. module:: gpiozero.pins.rpio
 
 .. autoclass:: gpiozero.pins.rpio.RPIOFactory
 
@@ -205,7 +207,7 @@ RPIO
 PiGPIO
 ======
 
-.. currentmodule:: gpiozero.pins.pigpio
+.. module:: gpiozero.pins.pigpio
 
 .. autoclass:: gpiozero.pins.pigpio.PiGPIOFactory
 
@@ -215,7 +217,7 @@ PiGPIO
 Native
 ======
 
-.. currentmodule:: gpiozero.pins.native
+.. module:: gpiozero.pins.native
 
 .. autoclass:: gpiozero.pins.native.NativeFactory
 
@@ -225,7 +227,7 @@ Native
 Mock
 ====
 
-.. currentmodule:: gpiozero.pins.mock
+.. module:: gpiozero.pins.mock
 
 .. autoclass:: gpiozero.pins.mock.MockFactory
     :members:

docs/api_spi.rst

@@ -1,6 +1,8 @@
-===========
+=================
-SPI Devices
+API - SPI Devices
-===========
+=================
+
+.. module:: gpiozero.spi_devices
 
 .. currentmodule:: gpiozero
 

docs/api_tools.rst

@@ -1,13 +1,13 @@
-============
+====================
-Source Tools
+API - Device Sources
-============
+====================
 
-.. currentmodule:: gpiozero.tools
+.. module:: gpiozero.tools
 
 GPIO Zero includes several utility routines which are intended to be used with
-the :doc:`source_values` attributes common to most devices in the library. These
+the :doc:`source_values` attributes common to most devices in the library.
-utility routines are in the ``tools`` module of GPIO Zero and are typically
+These utility routines are in the ``tools`` module of GPIO Zero and are
-imported as follows::
+typically imported as follows::
 
     from gpiozero.tools import scaled, negated, all_values
 

docs/api_utils.rst

@@ -1,20 +0,0 @@
-=========
-Utilities
-=========
-
-.. currentmodule:: gpiozero
-
-The GPIO Zero library also contains a database of information about the various
-revisions of Raspberry Pi. This is used internally to raise warnings when
-non-physical pins are used, or to raise exceptions when pull-downs are
-requested on pins with physical pull-up resistors attached. The following
-functions and classes can be used to query this database:
-
-.. autofunction:: pi_info
-
-.. autoclass:: PiBoardInfo
-
-.. autoclass:: HeaderInfo
-
-.. autoclass:: PinInfo
-

docs/index.rst

@@ -7,8 +7,16 @@ Table of Contents
     :maxdepth: 1
     :numbered:
 
-    recipes
     installing
+    recipes
+    recipes_advanced
+    remote_gpio
+    recipes_remote_gpio
+    source_values
+    cli_tools
+    faq
+    contributing
+    development
     api_input
     api_output
     api_spi
@@ -16,17 +24,9 @@ Table of Contents
     api_other
     api_generic
     api_tools
+    api_info
     api_pins
-    api_utils
     api_exc
-    cli_tools
-    source_values
-    remote_gpio
-    recipes_advanced
-    recipes_remote_gpio
-    faq
-    contributing
-    development
     changelog
     license
 

docs/recipes.rst

@@ -1,6 +1,6 @@
-================
+=============
-Recipes (Simple)
+Basic Recipes
-================
+=============
 
 .. currentmodule:: gpiozero
 
@@ -29,6 +29,8 @@ example, if an LED was attached to "GPIO17" you would specify the pin number as
 Importing GPIO Zero
 ===================
 
+.. module:: gpiozero
+
 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 into Python
 by default.

docs/recipes_advanced.rst

@@ -1,6 +1,6 @@
-==================
+================
-Recipes (Advanced)
+Advanced Recipes
-==================
+================
 
 .. currentmodule:: gpiozero
 

docs/remote_gpio.rst

@@ -1,6 +1,6 @@
-===========
+=======================
-Remote GPIO
+Configuring Remote GPIO
-===========
+=======================
 
 .. currentmodule:: gpiozero
 

docs/source_values.rst

@@ -14,9 +14,9 @@ which is equivalent to:
 
 .. literalinclude:: examples/led_button_loop.py
 
-Every device has a ``.value`` property (the device's current value). Input
+Every device has a :attr:`~Device.value` property (the device's current value).
-devices can only have their values read, but output devices can also have their
+Input devices can only have their values read, but output devices can also have
-value set to alter the state of the device::
+their value set to alter the state of the device::
 
     >>> led = PWMLED(17)
     >>> led.value  # LED is initially off
@@ -26,13 +26,15 @@ value set to alter the state of the device::
     1.0
     >>> led.value = 0  # LED is now off
 
-Every device also has a ``.values`` property (a generator continuously yielding
+Every device also has a :attr:`~ValuesMixin.values` property (a generator
-the device's current value). All output devices have a ``.source`` property
+continuously yielding the device's current value). All output devices have a
-which can be set to any iterator. The device will iterate over the values
+:attr:`~SourceMixin.source` property which can be set to any iterator. The
-provided, setting the device's value to each element at a rate specified in the
+device will iterate over the values provided, setting the device's value to
-``source_delay`` property.
+each element at a rate specified in the :attr:`~SourceMixin.source_delay`
+property.
 
 .. image:: images/source_values.*
+    :align: center
 
 The most common use case for this is to set the source of an output device to
 the values of an input device, like the example above. A more interesting
@@ -40,8 +42,9 @@ example would be a potentiometer controlling the brightness of an LED:
 
 .. literalinclude:: examples/pwmled_pot.py
 
-It is also possible to set an output device's ``source`` to the ``values`` of
+It is also possible to set an output device's :attr:`~SourceMixin.source` to
-another output device, to keep them matching:
+the :attr:`~ValuesMixin.values` of another output device, to keep them
+matching:
 
 .. literalinclude:: examples/matching_leds.py
 
@@ -49,6 +52,7 @@ The device's values can also be processed before they are passed to the
 ``source``:
 
 .. image:: images/source_value_processing.*
+    :align: center
 
 For example:
 
@@ -58,13 +62,14 @@ Alternatively, a custom generator can be used to provide values from an
 artificial source:
 
 .. image:: images/custom_generator.*
+    :align: center
 
 For example:
 
 .. literalinclude:: examples/custom_generator.py
 
 If the iterator is infinite (i.e. an infinite generator), the elements will be
-processed until the ``source`` is changed or set to ``None``.
+processed until the :attr:`~SourceMixin.source` is changed or set to ``None``.
 
 If the iterator is finite (e.g. a list), this will terminate once all elements
 are processed (leaving the device's value at the final element):
@@ -74,9 +79,10 @@ are processed (leaving the device's value at the final element):
 Composite devices
 -----------------
 
-Most devices have a ``value`` range between 0 and 1. Some have a range between
+Most devices have a :attr:`~Device.value` range between 0 and 1. Some have a
--1 and 1 (e.g. ``Motor``). The ``value`` of a composite device is a namedtuple
+range between -1 and 1 (e.g. :class:`Motor`). The :attr:`~Device.value` of a
-of such values. For example, the ``Robot`` class::
+composite device is a namedtuple of such values. For example, the
+:class:`Robot` class::
 
     >>> from gpiozero import Robot
     >>> robot = Robot(left=(14, 15), right=(17, 18))
@@ -95,8 +101,9 @@ of such values. For example, the ``Robot`` class::
 Source Tools
 ------------
 
-GPIO Zero provides a set of ready-made functions for dealing with source/values,
+GPIO Zero provides a set of ready-made functions for dealing with
-called source tools. These are available by importing from ``gpiozero.tools``.
+source/values, called source tools. These are available by importing from
+:mod:`gpiozero.tools`.
 
 Some of these source tools are artificial sources which require no input:
 
@@ -119,8 +126,8 @@ Some tools combine the values of multiple sources:
 
 .. image:: images/combining_sources.*
 
-In this example, the LED is lit only if both buttons are pressed (like an `AND`_
+In this example, the LED is lit only if both buttons are pressed (like an
-gate):
+`AND`_ gate):
 
 .. _AND: https://en.wikipedia.org/wiki/AND_gate