KevinMidboe/python-gpiozero
1
0
Fork 0
mirror of https://github.com/KevinMidboe/python-gpiozero.git synced 2025-10-29 09:40:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #576 from waveform80/docs-config

Browse Source 
Docs config
This commit is contained in:
Ben Nuttall
2017-07-16 12:23:49 +02:00
committed by GitHub
parent 978f8175da 69970dfc4b
commit b614fdc4f9
22 changed files with 352 additions and 237 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
Makefile
View File

@@ -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)

52
README.rst
View File

@@ -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
:target: https://badge.fury.io/py/gpiozero
:alt: Latest Version
.. image:: https://travis-ci.org/RPi-Distro/python-gpiozero.svg?branch=master
:target: https://travis-ci.org/RPi-Distro/python-gpiozero
:alt: Build Tests
.. image:: https://travis-ci.org/RPi-Distro/python-gpiozero.svg?branch=master
:target: https://travis-ci.org/RPi-Distro/python-gpiozero
:alt: Build Tests
.. 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
.. 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
how to get started.
colour LEDs, robotics kits and more. See the `Recipes`_ chapter of the
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/.
Development
===========
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
Please refer to the `Contributing`_ and `Development`_ chapters in the
documentation for information on contributing to the project.
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
.. _issues: https://github.com/RPi-Distro/python-gpiozero/issues
.. _recipes: https://gpiozero.readthedocs.io/en/latest/recipes.html
.. _Contribute: https://gpiozero.readthedocs.io/en/latest/contributing.html
.. _Recipes: http://gpiozero.readthedocs.io/en/latest/recipes.html
.. _Contributing: http://gpiozero.readthedocs.io/en/latest/contributing.html
.. _Development: http://gpiozero.readthedocs.io/en/latest/development.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

8
docs/api_boards.rst
View File

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

6
docs/api_exc.rst
View File

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

8
docs/api_generic.rst
View File

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

20
docs/api_info.rst Normal file
View File

@@ -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

8
docs/api_input.rst
View File

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

8
docs/api_other.rst
View File

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

8
docs/api_output.rst
View File

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

22
docs/api_pins.rst
View File

@@ -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:

8
docs/api_spi.rst
View File

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

14
docs/api_tools.rst
View File

@@ -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

20
docs/api_utils.rst
View File

@@ -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

20
docs/conf.py
View File

@@ -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_urls = False
latex_show_pagerefs = True
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 = []

160
docs/faq.rst Normal file
View File

@@ -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()

31
docs/index.rst
View File

@@ -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`

105
docs/notes.rst
View File

@@ -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/

33
docs/recipes.rst
View File

@@ -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
===

6
docs/recipes_advanced.rst
View File

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

6
docs/remote_gpio.rst
View File

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

43
docs/source_values.rst
View File

@@ -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

2
gpiozero/pins/__init__.py
View File

@@ -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: