Fix #565

Add mock pins docs and tidy up some other bits of the pins docs

docs/api_pins.rst

@@ -135,36 +135,22 @@ Like the ``GPIOZERO_PIN_FACTORY`` value, these can be exported from your
     Sensible uses of multiple pin factories are given in :doc:`remote_gpio`.
 
 
-RPi.GPIO
-========
+Mock pins
+=========
 
-.. autoclass:: gpiozero.pins.rpigpio.RPiGPIOFactory
+There's also a :class:`gpiozero.pins.mock.MockFactory` which generates entirely
+fake pins. This was originally intended for GPIO Zero developers who wish to
+write tests for devices without having to have the physical device wired in to
+their Pi. However, they have also proven relatively useful in developing GPIO
+Zero scripts without having a Pi to hand. This pin factory will never be loaded
+by default; it must be explicitly specified. For example:
 
-.. autoclass:: gpiozero.pins.rpigpio.RPiGPIOPin
+.. literalinclude:: examples/mock_demo.py
 
-
-RPIO
-====
-
-.. autoclass:: gpiozero.pins.rpio.RPIOFactory
-
-.. autoclass:: gpiozero.pins.rpio.RPIOPin
-
-
-PiGPIO
-======
-
-.. autoclass:: gpiozero.pins.pigpio.PiGPIOFactory
-
-.. autoclass:: gpiozero.pins.pigpio.PiGPIOPin
-
-
-Native
-======
-
-.. autoclass:: gpiozero.pins.native.NativeFactory
-
-.. autoclass:: gpiozero.pins.native.NativePin
+Several sub-classes of mock pins exist for emulating various other things
+(pins that do/don't support PWM, pins that are connected together, pins that
+drive high after a delay, etc). Interested users are invited to read the GPIO
+Zero test suite for further examples of usage.
 
 
 Base classes
@@ -196,22 +182,62 @@ Base classes
     :members:
 
 
-Utilities
-=========
+RPi.GPIO
+========
 
-The pins module 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:
+.. currentmodule:: gpiozero.pins.rpigpio
 
-.. currentmodule:: gpiozero
+.. autoclass:: gpiozero.pins.rpigpio.RPiGPIOFactory
 
-.. autofunction:: pi_info
+.. autoclass:: gpiozero.pins.rpigpio.RPiGPIOPin
 
-.. autoclass:: PiBoardInfo
 
-.. autoclass:: HeaderInfo
+RPIO
+====
 
-.. autoclass:: PinInfo
+.. currentmodule:: gpiozero.pins.rpio
+
+.. autoclass:: gpiozero.pins.rpio.RPIOFactory
+
+.. autoclass:: gpiozero.pins.rpio.RPIOPin
+
+
+PiGPIO
+======
+
+.. currentmodule:: gpiozero.pins.pigpio
+
+.. autoclass:: gpiozero.pins.pigpio.PiGPIOFactory
+
+.. autoclass:: gpiozero.pins.pigpio.PiGPIOPin
+
+
+Native
+======
+
+.. currentmodule:: gpiozero.pins.native
+
+.. autoclass:: gpiozero.pins.native.NativeFactory
+
+.. autoclass:: gpiozero.pins.native.NativePin
+
+
+Mock
+====
+
+.. currentmodule:: gpiozero.pins.mock
+
+.. autoclass:: gpiozero.pins.mock.MockFactory
+    :members:
+
+.. autoclass:: gpiozero.pins.mock.MockPin
+    :members:
+
+.. autoclass:: gpiozero.pins.mock.MockPWMPin
+
+.. autoclass:: gpiozero.pins.mock.MockConnectedPin
+
+.. autoclass:: gpiozero.pins.mock.MockChargingPin
+
+.. autoclass:: gpiozero.pins.mock.MockTriggerPin
 

docs/api_utils.rst

@@ -0,0 +1,20 @@
+=========
+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
+

docs/examples/mock_demo.py

@@ -0,0 +1,28 @@
+from gpiozero.pins.mock import MockFactory
+from gpiozero import Device, Button, LED
+from time import sleep
+
+# Set the default pin factory to a mock factory
+Device.pin_factory = MockFactory()
+
+# Construct a couple of devices attached to mock pins 16 and 17, and link the
+# devices
+led = LED(17)
+btn = Button(16)
+led.source = btn.values
+
+# Here the button isn't "pushed" so the LED's value should be False
+print(led.value)
+
+# Get a reference to mock pin 16 (used by the button)
+btn_pin = Device.pin_factory.pin(16)
+
+# Drive the pin low (this is what would happen eletrically when the button is
+# pushed)
+btn_pin.drive_low()
+sleep(0.1) # give source some time to re-read the button state
+print(led.value)
+
+btn_pin.drive_high()
+sleep(0.1)
+print(led.value)

docs/index.rst

@@ -17,6 +17,7 @@ Table of Contents
     api_generic
     api_tools
     api_pins
+    api_utils
     api_exc
     cli_tools
     source_values