Add some API docs and move away from API docs

bibliopixel/drivers/PiWS281X.py

@@ -59,24 +59,41 @@ class PiWS281X(DriverBase):
     Driver for controlling WS281X LEDs via the rpi_ws281x C-extension.
     Only supported on the Raspberry Pi 2, 3, and Zero
 
-    This driver needs to be run as sudo.
+    This driver needs to be run as sudo and requires the rpi_ws281x C extension.
+
+    Install rpi_ws281x with the following shell commands:
+
+        git clone https://github.com/jgarff/rpi_ws281x.git
+        cd rpi_ws281x
+
+        sudo apt-get install python-dev swig scons
+        sudo scons
+
+        cd python
+        # If using default system python3
+        sudo python3 setup.py build install
+        # If using virtualenv, enter env then run
+        python setup.py build install
+
+    Provides the same parameters of :py:class:`.driver_base.DriverBase` as
+    well as those below:
+
+    :param int gpio: GPIO pin to output to. Typically 18 or 13
+    :param int ledFreqHz: WS2812B base data frequency in Hz. Only change to
+        400000 if using very old WS218B LEDs
+    :param int ledDma: DMA channel to use for generating signal (Between 1 and 14)
+    :param bool ledInvert: True to invert the signal (when using NPN transistor level shift)
     """
     # Including follow as comment as URLs in docstrings don't play well with sphinx
     # Discussion re: running as sudo
     # https://groups.google.com/d/msg/maniacal-labs-users/6hV-2_-Xmqc/wmWJK709AQAJ
     # https://github.com/jgarff/rpi_ws281x/blob/master/python/neopixel.py#L106
 
     def __init__(
-            self, num, gamma=gamma.NEOPIXEL, c_order=ChannelOrder.RGB, gpio=18,
+            self, num, gamma=gamma.NEOPIXEL, c_order="RGB", gpio=18,
             ledFreqHz=800000, ledDma=5, ledInvert=False,
             color_channels=3, brightness=255, **kwds):
-        """
-        num - Number of LED pixels.
-        gpio - GPIO pin connected to the pixels (must support PWM! GPIO 13 or 18 (pins 33 or 12) on RPi 3).
-        ledFreqHz - LED signal frequency in hertz (800khz or 400khz)
-        ledDma - DMA channel to use for generating signal (Between 1 and 14)
-        ledInvert - True to invert the signal (when using NPN transistor level shift)
-        """
+
         if not NeoColor:
             raise ValueError(WS_ERROR)
         super().__init__(num, c_order=c_order, gamma=gamma, **kwds)

bibliopixel/drivers/SPI/APA102.py

@@ -4,7 +4,12 @@
 
 
 class APA102(SPIBase):
-    """Driver for APA102/SK9822 based LED strips on devices like the Raspberry Pi and BeagleBone"""
+    """Driver for APA102/SK9822 based LED strips on devices like
+    the Raspberry Pi and BeagleBone
+
+    Provides the same parameters as
+    :py:class:`bibliopixel.drivers.SPI.SPIBase`
+    """
 
     def __init__(self, num, gamma=gamma.APA102, **kwargs):
         super().__init__(num, gamma=gamma, **kwargs)

bibliopixel/drivers/SPI/LPD8806.py

@@ -5,7 +5,11 @@
 
 class LPD8806(SPIBase):
     """Main driver for LPD8806 based LED strips on devices like the Raspberry Pi
-       and BeagleBone."""
+       and BeagleBone.
+
+    Provides the same parameters as
+    :py:class:`bibliopixel.drivers.SPI.SPIBase`
+    """
 
     def __init__(self, num, gamma=gamma.LPD8806, **kwargs):
         super().__init__(num, gamma=gamma, **kwargs)

bibliopixel/drivers/SPI/WS2801.py

@@ -4,7 +4,12 @@
 
 
 class WS2801(SPIBase):
-    """Main driver for WS2801 based LED strips on devices like the Raspberry Pi and BeagleBone"""
+    """Main driver for WS2801 based LED strips on devices like the
+    Raspberry Pi and BeagleBone
+
+    Provides the same parameters as
+    :py:class:`bibliopixel.drivers.SPI.SPIBase`
+    """
 
     def __init__(self, num, gamma=gamma.WS2801, spi_speed=1, **kwargs):
         if not (0 < spi_speed <= 1):

bibliopixel/drivers/SPI/WS281X.py

@@ -11,6 +11,9 @@ class WS281X(SPIBase):
     """
     SPI driver for WS2812(b) based LED strips on devices like
     Raspberry Pi, OrangePi, BeagleBone,..
+
+    Provides the same parameters as
+    :py:class:`bibliopixel.drivers.SPI.SPIBase`
     """
 
     def __init__(self, num, gamma=_gamma.WS2812, spi_speed=3.2, **kwargs):

bibliopixel/drivers/SPI/base.py

@@ -6,7 +6,18 @@
 
 class SPIBase(DriverBase):
     """Base driver for controling SPI devices on systems like the Raspberry Pi
-       and BeagleBone"""
+      and BeagleBone
+
+    Provides the same parameters of
+    :py:class:`bibliopixel.drivers.driver_base.DriverBase` as
+    well as those below:
+
+    :param str dev: SPI device path
+    :param str spi_interface: Interface API with which to connect to the SPI
+        device. One of :py:class:`bibliopixel.drivers.spi_interfaces.SPI_INTERFACES`
+    :param int spi_speed: Output data rate, in MHz
+    :param interface: DEPRECATED - Use spi_interface
+    """
     def __init__(self, num, dev='/dev/spidev0.0',
                  spi_interface=None, spi_speed=1,
                  interface='FILE',  # DEPRECATED

bibliopixel/drivers/SPI/driver.py

@@ -22,7 +22,16 @@
 
 def SPI(ledtype=None, num=0, **kwargs):
     """Wrapper function for using SPI device drivers on systems like the
-    Raspberry Pi and BeagleBone"""
+    Raspberry Pi and BeagleBone. This allows using any of the SPI drivers
+    from a single entry point instead importing the driver for a specific
+    LED type.
+
+    Provides the same parameters of
+    :py:class:`bibliopixel.drivers.SPI.SPIBase` as
+    well as those below:
+
+    :param ledtype: One of: LPD8806, WS2801, WS281X, or APA102
+    """
 
     from ...project.types.ledtype import make
     if ledtype is None:

bibliopixel/drivers/SPI/interfaces.py

@@ -13,12 +13,15 @@ def __init__(self, dev, spi_speed):
         self._spi_speed = spi_speed
 
     def send_packet(self, data):
+        """SHOULD BE PRIVATE"""
         raise NotImplementedError
 
     def compute_packet(self, data):
+        """SHOULD BE PRIVATE"""
         return data
 
     def error(self, text):
+        """SHOULD BE PRIVATE"""
         msg = 'Error with dev: {}, spi_speed: {} - {}'.format(self._dev, self._spi_speed, text)
         log.error(msg)
         raise IOError(msg)
@@ -37,6 +40,7 @@ def __init__(self, **kwargs):
         log.info('file io spi dev {:s}'.format(self._dev))
 
     def send_packet(self, data):
+        """SHOULD BE PRIVATE"""
         package_size = 4032  # bit smaller than 4096 because of headers
         for i in range(int(math.ceil(len(data) / package_size))):
             start = i * package_size
@@ -63,6 +67,7 @@ def __init__(self, **kwargs):
             self._dev, self._spi.max_speed / 1e6))
 
     def send_packet(self, data):
+        """SHOULD BE PRIVATE"""
         package_size = 4032  # bit smaller than 4096 because of headers
         for i in range(int(math.ceil(len(data) / package_size))):
             start = i * package_size
@@ -106,6 +111,7 @@ def __init__(self, **kwargs):
             'py-spidev dev {:s} speed @ {:.2f} MHz'.format(self._dev, self._spi.max_speed_hz / 1e6))
 
     def send_packet(self, data):
+        """SHOULD BE PRIVATE"""
         self._spi.xfer2(list(data))
 
 

bibliopixel/drivers/SimPixel/SimpleWebSocketServer.py

@@ -1,7 +1,3 @@
-'''
-The MIT License (MIT)
-Copyright (c) 2013 Dave P.
-'''
 # flake8: noqa
 import sys
 VER = sys.version_info[0]

bibliopixel/drivers/SimPixel/driver.py

@@ -5,16 +5,23 @@
 
 
 class SimPixel(DriverBase):
+    """Output a simulation of your displat to the web-based
+    simulator at http://simpixel.io
+
+    Provides the same parameters of
+    :py:class:`bibliopixel.drivers.driver_base.DriverBase` as
+    well as those below:
+
+    :param int port: Port to serve websocket server on.
+    :param pixel_positions: Override the automatic generation of pyhsical
+        pixel layout. This value can be generated via the methods in
+        :py:mod:`bibliopixel.layout.geometry`
+    """
+
     CACHE = server_cache.ServerCache(websocket.Server, selectInterval=0.001)
 
     def __init__(self, num=1024, port=1337, pixel_positions=None, **kwds):
-        """
-        Args:
-            num:  number of LEDs being visualizer.
-            port:  the port on which the SimPixel server is running.
-            pixel_positions:  the positions of the LEDs in 3-d space.
-            **kwds:  keywords passed to DriverBase.
-        """
+
         super().__init__(num, **kwds)
         self.port = port
         self.pixel_positions = self.server = self.thread = None
@@ -23,18 +30,21 @@ def __init__(self, num=1024, port=1337, pixel_positions=None, **kwds):
             self.set_pixel_positions(pixel_positions)
 
     def start(self):
+        """SHOULD BE PRIVATE"""
         self.server = self.CACHE.get_server(self.port)
         if self.pixel_positions:
             self.server.update(positions=self.pixel_positions)
 
     def set_pixel_positions(self, pixel_positions):
+        """SHOULD BE PRIVATE"""
         # Flatten list of led positions.
         pl = [c for p in pixel_positions for c in p]
         self.pixel_positions = bytearray(struct.pack('<%sh' % len(pl), *pl))
         if self.server:
             self.server.update(positions=self.pixel_positions)
 
     def cleanup(self):
+        """SHOULD BE PRIVATE"""
         self.server.close()
 
     def _compute_packet(self):

bibliopixel/drivers/channel_order.py

@@ -1,4 +1,8 @@
 class ChannelOrder(object):
+    """
+    Helper class to automatically convert string values into tuple
+    values needed to define color channel order.
+    """
 
     RGB = 0, 1, 2
     RBG = 0, 2, 1

bibliopixel/drivers/driver_base.py

@@ -5,7 +5,15 @@
 
 
 class DriverBase(object):
-    """Base driver class to build other drivers from."""
+    """
+    Base driver class to build other drivers from.
+
+    :param int num: Number of total pixels held by this driver
+    :param int width: Width of matrix, for use with :py:class:`bibliopixel.layout.matrix.Matrix`
+    :param int height: Height of matrix, for use with :py:class:`bibliopixel.layout.matrix.Matrix`
+    :param str c_order: Color channel order
+    :param gamma: Gamma correction table. Preset tables available in :py:mod:`bibliopixel.util.colors.gamma`
+    """
 
     # If set_device_brightness is not empty, it's a method that allows you
     # to directly set the brightness for the device.
@@ -21,7 +29,7 @@ def construct(cls, project, **desc):
         """Construct a driver from a project and a description."""
         return cls(maker=project.maker, **desc)
 
-    def __init__(self, num=0, width=0, height=0, c_order=ChannelOrder.RGB,
+    def __init__(self, num=0, width=0, height=0, c_order="RGB",
                  gamma=None, maker=data_maker.MAKER, **kwds):
         attributes.set_reserved(self, 'driver', **kwds)
 
@@ -53,9 +61,23 @@ def __init__(self, num=0, width=0, height=0, c_order=ChannelOrder.RGB,
         self._waiting_brightness = None
 
     def set_pixel_positions(self, pixel_positions):
+        """
+        Internal Use Only
+
+        Placeholder callback for sending physical pixel layout data to the
+        :py:mod:`.SimPixel` driver.
+        """
         pass
 
     def set_colors(self, colors, pos):
+        """
+        Use with caution!
+
+        Directly set the pixel buffers.
+
+        :param colors: A list of color tuples
+        :param int pos: Position in color list to begin set operation.
+        """
         self._colors = colors
         self._pos = pos
 
@@ -78,6 +100,11 @@ def cleanup(self):
         pass
 
     def bufByteCount(self):
+        """
+        Total number of bytes that the pixel buffer represents.
+        Mainly used for drivers such as :py:mod:`bibliopixel.drivers.serial`
+        and :py:mod:`.network`
+        """
         return 3 * self.numLEDs
 
     def sync(self):
@@ -107,6 +134,11 @@ def _send_packet(self):
         pass
 
     def update_colors(self):
+        """Apply any corrections to the current color list
+        and send the results to the driver output. This function primarily
+        provided as a wrapper for each driver's implementation of
+        :py:func:`_compute_packet` and :py:func:`_send_packet`.
+        """
         start = time.time()
 
         with self.brightness_lock:
@@ -125,10 +157,19 @@ def update_colors(self):
         self.lastUpdate = time.time() - start
 
     def set_brightness(self, brightness):
+        """Set the global brightness for this driver's output.
+
+        :param int brightness: 0-255 value representing the desired
+            brightness level
+        """
         with self.brightness_lock:
             self._waiting_brightness = brightness
 
     def _render(self):
+        """Typically called from :py:func:`_compute_packet` this applies
+        brightness and gamma correction to the pixels controlled by this
+        driver.
+        """
         if self.set_device_brightness:
             level = 1.0
         else:

bibliopixel/drivers/hue.py

@@ -12,6 +12,15 @@
 
 
 class Hue(DriverBase):
+    """
+    Driver for interacting with Philips Hue lights.
+
+    Provides the same parameters of :py:class:`.driver_base.DriverBase` as
+    well as those below:
+
+    :param str ip: Network hostname or IP address of the Hue base.
+    :param list nameMap: List of names to map to each pixel index
+    """
 
     def __init__(self, num, ip, nameMap=None, **kwds):
         super().__init__(num, **kwds)

bibliopixel/drivers/ledtype.py

@@ -2,6 +2,10 @@
 
 
 class LEDTYPE(IntEnum):
+    """Enumerated LED type names to be used with
+    :py:mod:`bibliopixel.drivers.serial` and
+    :py:mod:`bibliopixel.drivers.SPI`
+    """
     GENERIC = 0  # Use if the serial device only supports one chipset
     LPD8806 = 1
     WS2801 = 2