Documenting positions

alphasign/interfaces/local.py

@@ -5,15 +5,20 @@ from alphasign.interfaces import base
 
 
 class Serial(base.BaseInterface):
+  """Connect to a sign through a local serial device.
+
+  This class uses `pySerial <http://pyserial.sourceforge.net/>`_.
+  """
   def __init__(self, device="/dev/ttyS0"):
+    """
+    :param device: character device (default: /dev/ttyS0)
+    :type device: string
+    """
     self.device = device
     self.debug = True
 
   def connect(self):
     """Establish connection to the device.
-
-    Args:
-      device: character device (default: /dev/ttyS0)
     """
     # TODO(ms): these settings can probably be tweaked and still support most of
     # the devices.
@@ -26,10 +31,17 @@ class Serial(base.BaseInterface):
                                rtscts=0)
 
   def disconnect(self):
+    """Disconnect from the device.
+    """
     if self._conn:
       self._conn.close()
 
   def write(self, packet):
+    """Write packet to the serial interface.
+
+    :param packet: packet to write
+    :type packet: :class:`alphasign.packet.Packet`
+    """
     if not self._conn:
       return
     if self.debug:
@@ -38,6 +50,10 @@ class Serial(base.BaseInterface):
 
 
 class DebugInterface(base.BaseInterface):
+  """Dummy interface used only for debugging.
+
+  This does nothing except print the contents of written packets.
+  """
   def __init__(self):
     self.debug = True
 

alphasign/modes.py

@@ -1,4 +1,60 @@
-# Display Modes (p89)
+"""
+This module defines available modes for use with TEXT files
+(:class:`alphasign.text.Text`).
+
+The following display modes are defined:
+
+* :const:`ROTATE`
+* :const:`HOLD`
+* :const:`ROLL_UP`
+* :const:`ROLL_DOWN`
+* :const:`ROLL_LEFT`
+* :const:`ROLL_RIGHT`
+* :const:`WIPE_UP`
+* :const:`WIPE_DOWN`
+* :const:`WIPE_LEFT`
+* :const:`WIPE_RIGHT`
+* :const:`SCROLL`
+* :const:`AUTOMODE`
+* :const:`ROLL_IN`
+* :const:`ROLL_OUT`
+* :const:`WIPE_IN`
+* :const:`WIPE_OUT`
+* :const:`COMPRESSED_ROTATE` (works only on certain sign models)
+* :const:`EXPLODE` (Alpha 3.0 protocol only)
+* :const:`CLOCK` (Alpha 3.0 protocol only)
+
+The following special modes are defined:
+
+* :const:`TWINKLE`
+* :const:`SPARKLE`
+* :const:`SNOW`
+* :const:`INTERLOCK`
+* :const:`SWITCH`
+* :const:`SLIDE` (only Betabrite 1036)
+* :const:`SPRAY`
+* :const:`STARBURST`
+* :const:`WELCOME`
+* :const:`SLOT_MACHINE`
+* :const:`NEWS_FLASH` (only Betabrite 1036)
+* :const:`TRUMPET_ANIMATION` (only Betabrite (1036)
+* :const:`CYCLE_COLORS` (only AlphaEclipse 3600)
+
+Special graphics are modes which display graphics before the message. The
+following special graphics are defined:
+
+* :const:`THANK_YOU`
+* :const:`NO_SMOKING`
+* :const:`DONT_DRINK_DRIVE`
+* :const:`RUNNING_ANIMAL`
+* :const:`FISH_ANIMATION`
+* :const:`FIREWORKS`
+* :const:`TURBO_CAR`
+* :const:`BALLOON_ANIMATION`
+* :const:`CHERRY_BOMB`
+"""
+
+# Normal display modes
 ROTATE            = "a"
 HOLD              = "b"
 FLASH             = "c"
@@ -16,9 +72,9 @@ ROLL_IN           = "p"
 ROLL_OUT          = "q"
 WIPE_IN           = "r"
 WIPE_OUT          = "s"
-COMPRESSED_ROTATE = "t"  # only available on certain sign models
-EXPLODE           = "u"  # alpha 3.0 protocol
-CLOCK             = "v"  # alpha 3.0 protocol
+COMPRESSED_ROTATE = "t"
+EXPLODE           = "u"
+CLOCK             = "v"
 
 # Special modes
 TWINKLE           = "n0"
@@ -26,16 +82,16 @@ SPARKLE           = "n1"
 SNOW              = "n2"
 INTERLOCK         = "n3"
 SWITCH            = "n4"
-SLIDE             = "n5"  # only Betabrite 1036
+SLIDE             = "n5"
 SPRAY             = "n6"
 STARBURST         = "n7"
 WELCOME           = "n8"
 SLOT_MACHINE      = "n9"
-NEWS_FLASH        = "nA"  # only Betabrite 1036
-TRUMPET_ANIMATION = "nB"  # only Betabrite 1036
-CYCLE_COLORS      = "nC"  # only AlphaEclipse 3600
+NEWS_FLASH        = "nA"
+TRUMPET_ANIMATION = "nB"
+CYCLE_COLORS      = "nC"
 
-# Special graphics (these display before the message)
+# Special graphics
 THANK_YOU         = "nS"
 NO_SMOKING        = "nU"
 DONT_DRINK_DRIVE  = "nV"

alphasign/packet.py

@@ -2,6 +2,11 @@ import constants
 
 
 class Packet(object):
+  """Container for data to be sent to a sign device.
+
+  Packet objects are created by other classes and should not usually be
+  instantiated directly.
+  """
   def __init__(self, contents):
     self.type     = "Z"            # Type Code (see protocol)
     self.address  = "00"           # Sign Address (see protocol)

alphasign/positions.py

@@ -1,7 +1,25 @@
+"""
+This module defines positions for use in TEXT files.
+
+The following position constants are defined:
+
+* :const:`MIDDLE_LINE`
+* :const:`TOP_LINE`
+* :const:`BOTTOM_LINE`
+* :const:`FILL`
+* :const:`LEFT`
+* :const:`RIGHT`
+
+:const:`LEFT` and :const:`RIGHT` only work on Alpha 3.0 protocol signs.
+
+Conditions and exceptions for these positions are described in Section 7.10 of
+the Alpha Sign Communications Protocol document.
+"""
+
 # Display positions
 MIDDLE_LINE = "\x20"
 TOP_LINE    = "\x22"
 BOTTOM_LINE = "\x26"
 FILL        = "\x30"
 LEFT        = "\x31"
-RIGHT       = "\x32"
+RIGHT       = "\x32"

alphasign/text.py

@@ -5,7 +5,16 @@ from packet import Packet
 
 
 class Text(object):
-  def __init__(self, data=None, label=None, size=None, position=None, mode=None):
+  """Class representing a TEXT file."""
+  def __init__(self, data=None, label=None, size=None,
+               position=None, mode=None):
+    """
+    :param data: initial string to insert into object
+    :param label: file label: (default: "A")
+    :param size: amount of bytes to allocate for object on sign (default: 64)
+    :param position: constant from :mod:`alphasign.positions`
+    :param mode: constant from :mod:`alphasign.modes`
+    """
     if data is None:
       data = ""
     if label is None: