From 9ed3a19a8e0a94f8f1dadfe403d32132a8089dd2 Mon Sep 17 00:00:00 2001 From: Dave Jones Date: Fri, 14 Jul 2017 10:44:57 +0100 Subject: [PATCH 1/8] Update docs config Add epub output, fix PDF output to include page-numbers in links (for printed output), reduce the (now ridiculous) length of the ToC by dropping it to one level, add numbering to chapters --- Makefile | 1 + docs/conf.py | 20 ++++++++++++++++---- docs/index.rst | 11 ++++++++++- 3 files changed, 27 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index dae7b25..4d7961c 100644 --- a/Makefile +++ b/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) diff --git a/docs/conf.py b/docs/conf.py index 259796e..fbbe280 100644 --- a/docs/conf.py +++ b/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_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 = [] diff --git a/docs/index.rst b/docs/index.rst index ad2fa6e..f2deb81 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,8 @@ Table of Contents ================= .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + :numbered: recipes notes @@ -28,3 +29,11 @@ Table of Contents development changelog license + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + From 366c22e637a5229763747389bedc308b3954a80a Mon Sep 17 00:00:00 2001 From: Dave Jones Date: Fri, 14 Jul 2017 13:39:11 +0100 Subject: [PATCH 2/8] First stab at a FAQ --- docs/faq.rst | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 87 insertions(+) create mode 100644 docs/faq.rst diff --git a/docs/faq.rst b/docs/faq.rst new file mode 100644 index 0000000..5ffc23d --- /dev/null +++ b/docs/faq.rst @@ -0,0 +1,86 @@ +.. _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. + diff --git a/docs/index.rst b/docs/index.rst index f2deb81..c3d385e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -25,6 +25,7 @@ Table of Contents remote_gpio recipes_advanced recipes_remote_gpio + faq contributing development changelog From cb4276e897a4ab32025e768ce8d28971080b89be Mon Sep 17 00:00:00 2001 From: Dave Jones Date: Fri, 14 Jul 2017 21:07:26 +0100 Subject: [PATCH 3/8] Split Notes into FAQ and Recipes Notes was always a bit of a "vague" section and half of it felt like FAQs. Hopefully this is a little more consistent --- docs/faq.rst | 74 +++++++++++++++++++++++++++++++++ docs/index.rst | 1 - docs/notes.rst | 105 ----------------------------------------------- docs/recipes.rst | 25 +++++++++++ 4 files changed, 99 insertions(+), 106 deletions(-) delete mode 100644 docs/notes.rst diff --git a/docs/faq.rst b/docs/faq.rst index 5ffc23d..59f4631 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -84,3 +84,77 @@ suppress the warnings you've got a couple of options: 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() + diff --git a/docs/index.rst b/docs/index.rst index c3d385e..89c800e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,7 +8,6 @@ Table of Contents :numbered: recipes - notes installing api_input api_output diff --git a/docs/notes.rst b/docs/notes.rst deleted file mode 100644 index b704a8d..0000000 --- a/docs/notes.rst +++ /dev/null @@ -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/ diff --git a/docs/recipes.rst b/docs/recipes.rst index 5d260d3..673ab4a 100644 --- a/docs/recipes.rst +++ b/docs/recipes.rst @@ -24,6 +24,31 @@ 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 + +Importing 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) LED === From 401f3a443701143f76c9182f01e55cf5870f7a8d Mon Sep 17 00:00:00 2001 From: Dave Jones Date: Fri, 14 Jul 2017 21:44:40 +0100 Subject: [PATCH 4/8] Fix attribute link --- gpiozero/pins/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gpiozero/pins/__init__.py b/gpiozero/pins/__init__.py index 70febc1..fcb7372 100644 --- a/gpiozero/pins/__init__.py +++ b/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: From 120a30a951e4edb1677c77f4d2b6a221fdea85d3 Mon Sep 17 00:00:00 2001 From: Dave Jones Date: Fri, 14 Jul 2017 21:45:12 +0100 Subject: [PATCH 5/8] Stop setup.py whinging Apparently :doc: is a Sphinx extension and when setup.py checks for strict ReST adherence, this fails the test. May need a work-around for ..only in the header yet. --- README.rst | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/README.rst b/README.rst index 2be469f..114d2e6 100644 --- a/README.rst +++ b/README.rst @@ -58,11 +58,11 @@ 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, @@ -76,13 +76,8 @@ 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. Contributors ============ @@ -111,10 +106,10 @@ 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 + .. _Ben Nuttall: https://github.com/bennuttall .. _Dave Jones: https://github.com/waveform80 .. _Andrew Scheller: https://github.com/lurch From 4cc4b1c132cf8a9e999835923bcebb6ac7268d3c Mon Sep 17 00:00:00 2001 From: Dave Jones Date: Fri, 14 Jul 2017 21:46:27 +0100 Subject: [PATCH 6/8] 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 | 8 +++++--- docs/api_exc.rst | 6 +++--- docs/api_generic.rst | 8 +++++--- docs/api_info.rst | 20 ++++++++++++++++++ docs/api_input.rst | 8 +++++--- docs/api_other.rst | 8 +++++--- docs/api_output.rst | 8 +++++--- docs/api_pins.rst | 22 +++++++++++--------- docs/api_spi.rst | 8 +++++--- docs/api_tools.rst | 14 ++++++------- docs/api_utils.rst | 20 ------------------ docs/index.rst | 20 +++++++++--------- docs/recipes.rst | 8 +++++--- docs/recipes_advanced.rst | 6 +++--- docs/remote_gpio.rst | 6 +++--- docs/source_values.rst | 43 +++++++++++++++++++++++---------------- 16 files changed, 118 insertions(+), 95 deletions(-) create mode 100644 docs/api_info.rst delete mode 100644 docs/api_utils.rst 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 From d3ee0c0102b5f2e38747fb8cc6f2606d2641d8ef Mon Sep 17 00:00:00 2001 From: Dave Jones Date: Fri, 14 Jul 2017 23:07:32 +0100 Subject: [PATCH 7/8] Switch pin numbering / import ordering Makes more sense, slightly better print layout --- docs/recipes.rst | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/recipes.rst b/docs/recipes.rst index 0a05a2c..b04fffe 100644 --- a/docs/recipes.rst +++ b/docs/recipes.rst @@ -8,24 +8,6 @@ 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! -.. _pin-numbering: - -Pin Numbering -============= - -This library uses Broadcom (BCM) pin numbering for the GPIO pins, as opposed -to physical (BOARD) numbering. Unlike in the `RPi.GPIO`_ library, this is not -configurable. - -.. _RPi.GPIO: https://pypi.python.org/pypi/RPi.GPIO - -Any pin marked "GPIO" in the diagram below can be used as a pin number. For -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 - Importing GPIO Zero =================== @@ -52,6 +34,24 @@ In this case, all references to items within GPIO Zero must be prefixed:: button = gpiozero.Button(2) +.. _pin-numbering: + +Pin Numbering +============= + +This library uses Broadcom (BCM) pin numbering for the GPIO pins, as opposed +to physical (BOARD) numbering. Unlike in the `RPi.GPIO`_ library, this is not +configurable. + +.. _RPi.GPIO: https://pypi.python.org/pypi/RPi.GPIO + +Any pin marked "GPIO" in the diagram below can be used as a pin number. For +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 === From 69970dfc4bb87d43217594cb0af58d5c20b9f1b7 Mon Sep 17 00:00:00 2001 From: Dave Jones Date: Sat, 15 Jul 2017 22:30:08 +0100 Subject: [PATCH 8/8] "only" is a Sphinx extension too ... apparently Doesn't render in GitHub, and setup.py whinges about it. Also about the duplicate "Development" anchor (due to the Development heading). All warnings now gone from setup.py, but we may need to find another means of excluding the badges from offline docs ... --- README.rst | 29 ++++++++++++----------------- 1 file changed, 12 insertions(+), 17 deletions(-) diff --git a/README.rst b/README.rst index 114d2e6..736c99e 100644 --- a/README.rst +++ b/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 - :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. @@ -66,18 +64,14 @@ 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 -=========== - Please refer to the `Contributing`_ and `Development`_ chapters in the -documentation. +documentation for information on contributing to the project. Contributors ============ @@ -109,6 +103,7 @@ Other contributors: .. _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