From cb4276e897a4ab32025e768ce8d28971080b89be Mon Sep 17 00:00:00 2001 From: Dave Jones Date: Fri, 14 Jul 2017 21:07:26 +0100 Subject: [PATCH] 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 ===