diff --git a/docs/api_boards.rst b/docs/api_boards.rst index 23c4730..a3eba88 100644 --- a/docs/api_boards.rst +++ b/docs/api_boards.rst @@ -1,6 +1,8 @@ -====================== -Boards and Accessories -====================== +============================ +API - Boards and Accessories +============================ + +.. module:: gpiozero.boards .. currentmodule:: gpiozero diff --git a/docs/api_exc.rst b/docs/api_exc.rst index 5d67aa1..4268cf8 100644 --- a/docs/api_exc.rst +++ b/docs/api_exc.rst @@ -1,6 +1,6 @@ -========== -Exceptions -========== +================ +API - Exceptions +================ .. currentmodule:: gpiozero diff --git a/docs/api_generic.rst b/docs/api_generic.rst index 8e1eb76..3a76ac5 100644 --- a/docs/api_generic.rst +++ b/docs/api_generic.rst @@ -1,6 +1,8 @@ -=============== -Generic Classes -=============== +===================== +API - Generic Classes +===================== + +.. module:: gpiozero.devices .. currentmodule:: gpiozero diff --git a/docs/api_info.rst b/docs/api_info.rst new file mode 100644 index 0000000..04ee5a6 --- /dev/null +++ b/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 + diff --git a/docs/api_input.rst b/docs/api_input.rst index 2629213..8c6b38e 100644 --- a/docs/api_input.rst +++ b/docs/api_input.rst @@ -1,6 +1,8 @@ -============= -Input Devices -============= +=================== +API - Input Devices +=================== + +.. module:: gpiozero.input_devices .. currentmodule:: gpiozero diff --git a/docs/api_other.rst b/docs/api_other.rst index 35729dd..ea78c07 100644 --- a/docs/api_other.rst +++ b/docs/api_other.rst @@ -1,6 +1,8 @@ -================ -Internal Devices -================ +====================== +API - Internal Devices +====================== + +.. module:: gpiozero.other_devices .. currentmodule:: gpiozero diff --git a/docs/api_output.rst b/docs/api_output.rst index b800773..bdb98d6 100644 --- a/docs/api_output.rst +++ b/docs/api_output.rst @@ -1,6 +1,8 @@ -============== -Output Devices -============== +==================== +API - Output Devices +==================== + +.. module:: gpiozero.output_devices .. currentmodule:: gpiozero diff --git a/docs/api_pins.rst b/docs/api_pins.rst index 2342e60..e15017f 100644 --- a/docs/api_pins.rst +++ b/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: diff --git a/docs/api_spi.rst b/docs/api_spi.rst index 85ddcd5..c2b671c 100644 --- a/docs/api_spi.rst +++ b/docs/api_spi.rst @@ -1,6 +1,8 @@ -=========== -SPI Devices -=========== +================= +API - SPI Devices +================= + +.. module:: gpiozero.spi_devices .. currentmodule:: gpiozero diff --git a/docs/api_tools.rst b/docs/api_tools.rst index 185eb19..76e16d1 100644 --- a/docs/api_tools.rst +++ b/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 -utility routines are in the ``tools`` module of GPIO Zero and are typically -imported as follows:: +the :doc:`source_values` attributes common to most devices in the library. +These utility routines are in the ``tools`` module of GPIO Zero and are +typically imported as follows:: from gpiozero.tools import scaled, negated, all_values diff --git a/docs/api_utils.rst b/docs/api_utils.rst deleted file mode 100644 index 6c22b1f..0000000 --- a/docs/api_utils.rst +++ /dev/null @@ -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 - diff --git a/docs/index.rst b/docs/index.rst index 89c800e..0782f47 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/recipes.rst b/docs/recipes.rst index 673ab4a..0a05a2c 100644 --- a/docs/recipes.rst +++ b/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. diff --git a/docs/recipes_advanced.rst b/docs/recipes_advanced.rst index 39db647..d7146ea 100644 --- a/docs/recipes_advanced.rst +++ b/docs/recipes_advanced.rst @@ -1,6 +1,6 @@ -================== -Recipes (Advanced) -================== +================ +Advanced Recipes +================ .. currentmodule:: gpiozero diff --git a/docs/remote_gpio.rst b/docs/remote_gpio.rst index e527e77..78a774e 100644 --- a/docs/remote_gpio.rst +++ b/docs/remote_gpio.rst @@ -1,6 +1,6 @@ -=========== -Remote GPIO -=========== +======================= +Configuring Remote GPIO +======================= .. currentmodule:: gpiozero diff --git a/docs/source_values.rst b/docs/source_values.rst index 4b108d9..6583f93 100644 --- a/docs/source_values.rst +++ b/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 -devices can only have their values read, but output devices can also have their -value set to alter the state of the device:: +Every device has a :attr:`~Device.value` property (the device's current value). +Input devices can only have their values read, but output devices can also have +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 -the device's current value). All output devices have a ``.source`` property -which can be set to any iterator. The device will iterate over the values -provided, setting the device's value to each element at a rate specified in the -``source_delay`` property. +Every device also has a :attr:`~ValuesMixin.values` property (a generator +continuously yielding the device's current value). All output devices have a +:attr:`~SourceMixin.source` property which can be set to any iterator. The +device will iterate over the values provided, setting the device's value to +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 -another output device, to keep them matching: +It is also possible to set an output device's :attr:`~SourceMixin.source` to +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 --1 and 1 (e.g. ``Motor``). The ``value`` of a composite device is a namedtuple -of such values. For example, the ``Robot`` class:: +Most devices have a :attr:`~Device.value` range between 0 and 1. Some have a +range between -1 and 1 (e.g. :class:`Motor`). The :attr:`~Device.value` of a +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, -called source tools. These are available by importing from ``gpiozero.tools``. +GPIO Zero provides a set of ready-made functions for dealing with +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`_ -gate): +In this example, the LED is lit only if both buttons are pressed (like an +`AND`_ gate): .. _AND: https://en.wikipedia.org/wiki/AND_gate