First stab at a FAQ

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.
+

docs/index.rst

@@ -25,6 +25,7 @@ Table of Contents
     remote_gpio
     recipes_advanced
     recipes_remote_gpio
+    faq
     contributing
     development
     changelog