Fix #565

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

gpiozero/pins/__init__.py

@@ -30,15 +30,9 @@ from ..exc import (
 
 class Factory(object):
     """
-    Generates pins, SPI, and I2C interfaces for devices. This is an abstract
-    base class for pin factories. Descendents *must* override the following
-    methods:
-
-    * :meth:`_get_address`
-    * :meth:`pin_address`
-
-    Descendents *may* additionally override the following methods, if
-    applicable:
+    Generates pins and SPI interfaces for devices. This is an abstract
+    base class for pin factories. Descendents *may* override the following
+    methods, if applicable:
 
     * :meth:`close`
     * :meth:`reserve_pins`
@@ -129,9 +123,6 @@ class Factory(object):
         """
         raise PinSPIUnsupported('SPI not supported by this pin factory')
 
-    def _get_address(self):
-        raise NotImplementedError
-
     def _get_pi_info(self):
         return None
 

gpiozero/pins/mock.py

@@ -216,7 +216,7 @@ class MockChargingPin(MockPin):
 class MockTriggerPin(MockPin):
     """
     This derivative of :class:`MockPin` is intended to be used with another
-    :class:`MockPin` to emulate a distance sensor. Set :attr:`echo_pin` to the
+    :class:`MockPin` to emulate a distance sensor. Set *echo_pin* to the
     corresponding pin instance. When this pin is driven high it will trigger
     the echo pin to drive high for the echo time.
     """
@@ -410,6 +410,14 @@ class MockSPIDevice(object):
 
 
 class MockFactory(LocalPiFactory):
+    """
+    Factory for generating mock pins. The *revision* parameter specifies what
+    revision of Pi the mock factory pretends to be (this affects the result of
+    the :attr:`pi_info` attribute as well as where pull-ups are assumed to be).
+    The *pin_class* attribute specifies which mock pin class will be generated
+    by the :meth:`pin` method by default. This can be changed after
+    construction by modifying the :attr:`pin_class` attribute.
+    """
     def __init__(
             self, revision=os.getenv('GPIOZERO_MOCK_REVISION', 'a02082'),
             pin_class=os.getenv('GPIOZERO_MOCK_PIN_CLASS', MockPin)):
@@ -427,10 +435,22 @@ class MockFactory(LocalPiFactory):
         return self._revision
 
     def reset(self):
+        """
+        Clears the pins and reservations sets. This is primarily useful in
+        test suites to ensure the pin factory is back in a "clean" state before
+        the next set of tests are run.
+        """
         self.pins.clear()
         self._reservations.clear()
 
     def pin(self, spec, pin_class=None, **kwargs):
+        """
+        The pin method for :class:`MockFactory` additionally takes a *pin_class*
+        attribute which can be used to override the class' :attr:`pin_class`
+        attribute. Any additional keyword arguments will be passed along to the
+        pin constructor (useful with things like :class:`MockConnectedPin` which
+        expect to be constructed with another pin).
+        """
         if pin_class is None:
             pin_class = self.pin_class
         n = self._to_gpio(spec)

gpiozero/pins/native.py

@@ -178,6 +178,9 @@ class NativeFactory(LocalPiFactory):
 
 
 class NativePin(LocalPiPin):
+    """
+    Native pin implementation. See :class:`NativeFactory` for more information.
+    """
     GPIO_FUNCTIONS = {
         'input':   0b000,
         'output':  0b001,

gpiozero/pins/pigpio.py

@@ -133,6 +133,12 @@ class PiGPIOFactory(PiFactory):
 
 
 class PiGPIOPin(PiPin):
+    """
+    Pin implementation for the `pigpio`_ library. See :class:`PiGPIOFactory`
+    for more information.
+
+    .. _pigpio: http://abyz.co.uk/rpi/pigpio/
+    """
     _CONNECTIONS = {} # maps (host, port) to (connection, pi_info)
     GPIO_FUNCTIONS = {
         'input':   pigpio.INPUT,
@@ -290,6 +296,12 @@ class PiGPIOPin(PiPin):
 
 
 class PiGPIOHardwareSPI(SPI, Device):
+    """
+    Hardware SPI implementation for the `pigpio`_ library. Uses the ``spi_*``
+    functions from the pigpio API.
+
+    .. _pigpio: http://abyz.co.uk/rpi/pigpio/
+    """
     def __init__(self, factory, port, device):
         self._port = port
         self._device = device
@@ -386,6 +398,12 @@ class PiGPIOHardwareSPI(SPI, Device):
 
 
 class PiGPIOSoftwareSPI(SPI, Device):
+    """
+    Software SPI implementation for the `pigpio`_ library. Uses the ``bb_spi_*``
+    functions from the pigpio API.
+
+    .. _pigpio: http://abyz.co.uk/rpi/pigpio/
+    """
     def __init__(self, factory, clock_pin, mosi_pin, miso_pin, select_pin):
         self._closed = True
         self._select_pin = select_pin

gpiozero/pins/rpigpio.py

@@ -58,6 +58,12 @@ class RPiGPIOFactory(LocalPiFactory):
 
 
 class RPiGPIOPin(LocalPiPin):
+    """
+    Pin implementation for the `RPi.GPIO`_ library. See :class:`RPiGPIOFactory`
+    for more information.
+
+    .. _RPi.GPIO: https://pypi.python.org/pypi/RPi.GPIO
+    """
     GPIO_FUNCTIONS = {
         'input':   GPIO.IN,
         'output':  GPIO.OUT,

gpiozero/pins/rpio.py

@@ -64,6 +64,12 @@ class RPIOFactory(LocalPiFactory):
 
 
 class RPIOPin(LocalPiPin):
+    """
+    Pin implementation for the `RPIO`_ library. See :class:`RPIOFactory` for
+    more information.
+
+    .. _RPIO: https://pythonhosted.org/RPIO/
+    """
     GPIO_FUNCTIONS = {
         'input':   RPIO.IN,
         'output':  RPIO.OUT,