Merge pull request #576 from waveform80/docs-config

Docs config

Makefile

@@ -80,6 +80,7 @@ install: $(SUBDIRS)
 doc: $(DOC_SOURCES)
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
+	$(MAKE) -C docs epub
 	$(MAKE) -C docs latexpdf
 
 source: $(DIST_TAR) $(DIST_ZIP)

README.rst

@@ -2,19 +2,17 @@
 gpiozero
 ========
 
-.. only:: builder_html
+.. image:: https://badge.fury.io/py/gpiozero.svg
+    :target: https://badge.fury.io/py/gpiozero
+    :alt: Latest Version
 
-    .. image:: https://badge.fury.io/py/gpiozero.svg
+.. image:: https://travis-ci.org/RPi-Distro/python-gpiozero.svg?branch=master
-        :target: https://badge.fury.io/py/gpiozero
+    :target: https://travis-ci.org/RPi-Distro/python-gpiozero
-        :alt: Latest Version
+    :alt: Build Tests
 
-    .. image:: https://travis-ci.org/RPi-Distro/python-gpiozero.svg?branch=master
+.. image:: https://img.shields.io/codecov/c/github/RPi-Distro/python-gpiozero/master.svg?maxAge=2592000
-        :target: https://travis-ci.org/RPi-Distro/python-gpiozero
+    :target: https://codecov.io/github/RPi-Distro/python-gpiozero
-        :alt: Build Tests
+    :alt: Code Coverage
-
-    .. image:: https://img.shields.io/codecov/c/github/RPi-Distro/python-gpiozero/master.svg?maxAge=2592000
-        :target: https://codecov.io/github/RPi-Distro/python-gpiozero
-        :alt: Code Coverage
 
 A simple interface to GPIO devices with Raspberry Pi.
 
@@ -58,31 +56,22 @@ together:
 
 The library includes interfaces to many simple everyday components, as well as
 some more complex things like sensors, analogue-to-digital converters, full
-colour LEDs, robotics kits and more. See the :doc:`recipes` page for ideas on
+colour LEDs, robotics kits and more. See the `Recipes`_ chapter of the
-how to get started.
+documentation for ideas on how to get started.
 
-Install
+Installation
-=======
+============
 
 GPIO Zero is installed by default in Raspbian Jessie, available from
 `raspberrypi.org`_. To install on Jessie Lite or other operating systems,
-including for PCs using remote GPIO, see the :doc:`installing` page.
+including for PCs using remote GPIO, see the `Installing`_ chapter.
 
 Documentation
 =============
 
 Comprehensive documentation is available at https://gpiozero.readthedocs.io/.
-
+Please refer to the `Contributing`_ and `Development`_ chapters in the
-Development
+documentation for information on contributing to the project.
-===========
-
-This project is being developed on `GitHub`_. Join in:
-
-* Provide suggestions, report bugs and ask questions as `issues`_
-* Provide examples we can use as `recipes`_
-* `Contribute`_ to the code
-
-Alternatively, email suggestions and feedback to ben@raspberrypi.org
 
 Contributors
 ============
@@ -111,10 +100,11 @@ Other contributors:
 
 .. _Raspberry Pi Foundation: https://www.raspberrypi.org/
 .. _raspberrypi.org: https://www.raspberrypi.org/downloads/
-.. _GitHub: https://github.com/RPi-Distro/python-gpiozero
+.. _Recipes: http://gpiozero.readthedocs.io/en/latest/recipes.html
-.. _issues: https://github.com/RPi-Distro/python-gpiozero/issues
+.. _Contributing: http://gpiozero.readthedocs.io/en/latest/contributing.html
-.. _recipes: https://gpiozero.readthedocs.io/en/latest/recipes.html
+.. _Development: http://gpiozero.readthedocs.io/en/latest/development.html
-.. _Contribute: https://gpiozero.readthedocs.io/en/latest/contributing.html
+.. _Installing: http://gpiozero.readthedocs/io/en/latest/installing.html
+
 .. _Ben Nuttall: https://github.com/bennuttall
 .. _Dave Jones: https://github.com/waveform80
 .. _Andrew Scheller: https://github.com/lurch

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/conf.py

@@ -89,8 +89,8 @@ else:
     html_theme = 'default'
     #html_theme_options = {}
     #html_sidebars = {}
+html_title = '%s %s Documentation' % (project, version)
 #html_theme_path = []
-#html_title = None
 #html_short_title = None
 #html_logo = None
 #html_favicon = None
@@ -119,7 +119,7 @@ htmlhelp_basename = '%sdoc' % _setup.__project__
 latex_elements = {
     'papersize': 'a4paper',
     'pointsize': '10pt',
-    #'preamble': '',
+    'preamble': r'\def\thempfootnote{\arabic{mpfootnote}}', # workaround sphinx issue #2530
 }
 
 latex_documents = [
@@ -129,16 +129,28 @@ latex_documents = [
         '%s Documentation' % project,  # title
         _setup.__author__,             # author
         'manual',                      # documentclass
+        True,                          # documents ref'd from toctree only
         ),
 ]
 
 #latex_logo = None
 #latex_use_parts = False
-#latex_show_pagerefs = False
+latex_show_pagerefs = True
-#latex_show_urls = False
+latex_show_urls = 'footnote'
 #latex_appendices = []
 #latex_domain_indices = True
 
+# -- Options for epub output ----------------------------------------------
+
+epub_basename = _setup.__project__
+#epub_theme = 'epub'
+#epub_title = html_title
+epub_author = _setup.__author__
+epub_identifier = 'https://gpiozero.readthedocs.io/'
+#epub_tocdepth = 3
+epub_show_urls = 'no'
+#epub_use_index = True
+
 # -- Options for manual page output ---------------------------------------
 
 man_pages = []

docs/faq.rst

@@ -0,0 +1,160 @@
+.. _faq:
+
+==========================
+Frequently Asked Questions
+==========================
+
+.. currentmodule:: gpiozero
+
+
+My event handler isn't being called?
+====================================
+
+When assigning event handlers, don't call the function you're assigning. For
+example::
+
+    from gpiozero import Button
+
+    def pushed():
+        print("Don't push the button!")
+
+    b = Button(17)
+    b.when_pressed = pushed()
+
+In the case above, when assigning to the ``when_pressed``, the thing that is
+assigned is the *result of calling* the ``pushed`` function. Because ``pushed``
+doesn't explicitly return anything, the result is ``None``. Hence this is
+equivalent to doing::
+
+    b.when_pressed = None
+
+This doesn't raise an error because it's perfectly valid: it's what you assign
+when you don't want the event handler to do anything. Instead, you want to
+do the following::
+
+    b.when_pressed = pushed
+
+This will assign the function to the event handler *without calling it*. This
+is the crucial difference between ``my_function`` (a reference to a function)
+and ``my_function()`` (the result of calling a function).
+
+
+Why do I get PinFactoryFallback warnings when I import gpiozero?
+================================================================
+
+You are most likely working in a virtual Python environment and have forgotten
+to install a pin driver library like ``RPi.GPIO``. GPIO Zero relies upon lower
+level pin drivers to handle interfacing to the GPIO pins on the Raspberry Pi,
+so you can eliminate the warning simply by installing GPIO Zero's first
+preference:
+
+.. code-block:: console
+
+    $ pip install rpi.gpio
+
+When GPIO Zero is imported it attempts to find a pin driver by importing them
+in a preferred order (detailed in :doc:`api_pins`). If it fails to load its
+first preference (``RPi.GPIO``) it notifies you with a warning, then falls back
+to trying its second preference and so on. Eventually it will fall back all the
+way to the ``native`` implementation. This is a pure Python implementation
+built into GPIO Zero itself. While this will work for most things it's almost
+certainly not what you want (it doesn't support PWM, and it's quite slow at
+certain things).
+
+If you want to use a pin driver other than the default, and you want to
+suppress the warnings you've got a couple of options:
+
+1. Explicitly specify what pin driver you want via an environment variable. For
+   example:
+
+   .. code-block:: console
+
+       $ GPIOZERO_PIN_FACTORY=pigpio python
+
+   In this case no warning is issued because there's no fallback; either the
+   specified factory loads or it fails in which case an :exc:`ImportError` will
+   be raised.
+
+2. Suppress the warnings and let the fallback mechanism work::
+
+    >>> import warnings
+    >>> warnings.simplefilter('ignore')
+    >>> import gpiozero
+
+   Refer to the :mod:`warnings` module documentation for more refined ways to
+   filter out specific warning classes.
+
+
+How can I tell what version of gpiozero I have installed?
+=========================================================
+
+The gpiozero library relies on the setuptools package for installation
+services.  You can use the setuptools ``pkg_resources`` API to query which
+version of gpiozero is available in your Python environment like so:
+
+.. code-block:: pycon
+
+    >>> from pkg_resources import require
+    >>> require('gpiozero')
+    [gpiozero 1.3.2 (/usr/lib/python3/dist-packages)]
+    >>> require('gpiozero')[0].version
+    '1.3.2'
+
+If you have multiple versions installed (e.g. from ``pip`` and ``apt``) they
+will not show up in the list returned by the ``require`` method. However, the
+first entry in the list will be the version that ``import gpiozero`` will
+import.
+
+If you receive the error "No module named pkg_resources", you need to install
+the ``pip`` utility. This can be done with the following command in Raspbian:
+
+.. code-block:: console
+
+    $ sudo apt install python-pip
+
+Alternatively, install pip with `get-pip`_.
+
+.. _get-pip: https://pip.pypa.io/en/stable/installing/
+
+
+.. _keep-your-script-running:
+
+How do I keep my script running?
+================================
+
+The following script looks like it should turn an LED on::
+
+    from gpiozero import LED
+
+    led = LED(17)
+    led.on()
+
+And it does, if you're using the Python (or IPython or IDLE) shell. However,
+if you saved this script as a Python file and ran it, it would flash on
+briefly, then the script would end and it would turn off.
+
+The following file includes an intentional :func:`~signal.pause` to keep the
+script alive::
+
+    from gpiozero import LED
+    from signal import pause
+
+    led = LED(17)
+    led.on()
+    pause()
+
+Now the script will stay running, leaving the LED on, until it is terminated
+manually (e.g. by pressing Ctrl+C). Similarly, when setting up callbacks on
+button presses or other input devices, the script 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 = hello
+    pause()
+

docs/index.rst

@@ -4,11 +4,19 @@ Table of Contents
 =================
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
+    :numbered:
 
-    recipes
-    notes
     installing
+    recipes
+    recipes_advanced
+    remote_gpio
+    recipes_remote_gpio
+    source_values
+    cli_tools
+    faq
+    contributing
+    development
     api_input
     api_output
     api_spi
@@ -16,15 +24,16 @@ 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
-    contributing
-    development
     changelog
     license
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

docs/notes.rst

@@ -1,105 +0,0 @@
-=====
-Notes
-=====
-
-.. currentmodule:: gpiozero
-
-
-.. _keep-your-script-running:
-
-Keep your script running
-========================
-
-The following script looks like it should turn an LED on::
-
-    from gpiozero import LED
-
-    led = LED(17)
-    led.on()
-
-And it does, if you're using the Python (or IPython or IDLE) shell. However,
-if you saved this script as a Python file and ran it, it would flash on
-briefly, then the script would end and it would turn off.
-
-The following file includes an intentional :func:`~signal.pause` to keep the
-script alive::
-
-    from gpiozero import LED
-    from signal import pause
-
-    led = LED(17)
-    led.on()
-    pause()
-
-Now the script will stay running, leaving the LED on, until it is terminated
-manually (e.g. by pressing Ctrl+C). Similarly, when setting up callbacks on
-button presses or other input devices, the script 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 = 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 into Python
-by default.
-
-For example, to use the :class:`Button` interface from GPIO Zero, it
-should be explicitly imported::
-
-    from gpiozero import Button
-
-Now :class:`~gpiozero.Button` is available directly in your script::
-
-    button = Button(2)
-
-Alternatively, the whole GPIO Zero library can be imported::
-
-    import gpiozero
-
-In this case, all references to items within GPIO Zero must be prefixed::
-
-    button = gpiozero.Button(2)
-
-
-How can I tell what version of gpiozero I have installed?
-=========================================================
-
-The gpiozero library relies on the setuptools package for installation
-services.  You can use the setuptools ``pkg_resources`` API to query which
-version of gpiozero is available in your Python environment like so:
-
-.. code-block:: pycon
-
-    >>> from pkg_resources import require
-    >>> require('gpiozero')
-    [gpiozero 1.3.2 (/usr/lib/python3/dist-packages)]
-    >>> require('gpiozero')[0].version
-    '1.3.2'
-
-If you have multiple versions installed (e.g. from ``pip`` and ``apt``) they
-will not show up in the list returned by the ``require`` method. However, the
-first entry in the list will be the version that ``import gpiozero`` will
-import.
-
-If you receive the error "No module named pkg_resources", you need to install
-the ``pip`` utility. This can be done with the following command in Raspbian:
-
-.. code-block:: console
-
-    sudo apt install python-pip
-
-Alternatively, install pip with `get-pip`_.
-
-
-.. _get-pip: https://pip.pypa.io/en/stable/installing/

docs/recipes.rst

@@ -1,6 +1,6 @@
-================
+=============
-Recipes (Simple)
+Basic Recipes
-================
+=============
 
 .. currentmodule:: gpiozero
 
@@ -8,6 +8,32 @@ The following recipes demonstrate some of the capabilities of the GPIO Zero
 library. Please note that all recipes are written assuming Python 3. Recipes
 *may* work under Python 2, but no guarantees!
 
+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.
+
+For example, to use the :class:`Button` interface from GPIO Zero, it
+should be explicitly imported::
+
+    from gpiozero import Button
+
+Now :class:`~gpiozero.Button` is available directly in your script::
+
+    button = Button(2)
+
+Alternatively, the whole GPIO Zero library can be imported::
+
+    import gpiozero
+
+In this case, all references to items within GPIO Zero must be prefixed::
+
+    button = gpiozero.Button(2)
+
 .. _pin-numbering:
 
 Pin Numbering
@@ -24,6 +50,7 @@ example, if an LED was attached to "GPIO17" you would specify the pin number as
 17 rather than 11:
 
 .. image:: images/pin_layout.*
+    :align: center
 
 LED
 ===

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
 

gpiozero/pins/__init__.py

@@ -322,7 +322,7 @@ class Pin(object):
         detection, measured in seconds. If bounce detection is not currently in
         use, this is ``None``.
 
-        For example, if :attr:`edge` is currently "rising", :attr:`bounce` is
+        For example, if :attr:`edges` is currently "rising", :attr:`bounce` is
         currently 5/1000 (5ms), then the waveform below will only fire
         :attr:`when_changed` on two occasions despite there being three rising
         edges: