Adding documentation for date and time

alphasign/date.py

@@ -3,24 +3,25 @@ from packet import Packet
 
 
 class Date(object):
+  """Class for setting and accessing the date."""
+
   def call_date(self, format=0):
     """Call date for insertion into a TEXT file.
 
-    Args:
-      format: integer from 0 to 9
-                0 - MM/DD/YY
-                1 - DD/MM/YY
-                2 - MM-DD-YY
-                3 - DD-MM-YY
-                4 - MM.DD.YY
-                5 - DD.MM.YY
-                6 - MM DD YY
-                7 - DD MM YY
-                8 - MMM.DD, YYYY
-                9 - Day of week
+    :param format: integer from 0 to 9:
+                     0 - MM/DD/YY;
+                     1 - DD/MM/YY;
+                     2 - MM-DD-YY;
+                     3 - DD-MM-YY;
+                     4 - MM.DD.YY;
+                     5 - DD.MM.YY;
+                     6 - MM DD YY;
+                     7 - DD MM YY;
+                     8 - MMM.DD, YYYY;
+                     9 - Day of week
 
-    Returns:
-      formatted string to use in a TEXT
+    :returns: formatted string to use in a TEXT
+    :rtype: string
     """
     if format < 0 or format > 9:
       format = 0
@@ -33,10 +34,11 @@ class Date(object):
 
     If the date is not specified in the arguments, today's date will be used.
 
-    Args:
-      year (optional): two-digit year (98, 99, 00, ...)
-      month (optional): integer month (1, 2, ..., 12)
-      day (optional): integer day (1, ..., 31)
+    :param year: (optional) two-digit year (98, 99, 00, ...)
+    :param month: (optional) integer month (1, 2, ..., 12)
+    :param day: (optional) integer day (1, ..., 31)
+
+    :rtype: :class:`alphasign.packet.Packet` object
     """
     today = datetime.datetime.today()
     if year is None:
@@ -55,8 +57,9 @@ class Date(object):
 
     If the argument is omitted, today's day will be used.
 
-    Args:
-      day (optional): integer between 1 (Sunday) and 7 (Saturday)
+    :param day: (optional) integer between 1 (Sunday) and 7 (Saturday)
+
+    :rtype: :class:`alphasign.packet.Packet` object
     """
     if day is None or day < 1 or day > 7:
       day = datetime.datetime.today().weekday() + 1

alphasign/packet.py

@@ -7,9 +7,10 @@ class Packet(object):
   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)
+    self.type     = "Z"   # Type Code (see protocol)
+    self.address  = "00"  # Sign Address (see protocol)
     self._pkt = ("%s%s%s%s%s%s%s" %
                  (constants.NUL * 5, constants.SOH, self.type,
                   self.address, constants.STX, contents,

alphasign/string.py

@@ -4,6 +4,7 @@ from packet import Packet
 
 class String(object):
   """Class representing a STRING file."""
+
   def __init__(self, data=None, label=None, size=None):
     """
     :param data: initial string to insert into object
@@ -31,8 +32,8 @@ class String(object):
 
     This is for inserting a STRING file into a TEXT file.
 
-    Returns:
-      control code and specified string label
+    :returns: control code and specified string label
+    :rtype: string
     """
     return "\x10%s" % self.label
 
@@ -42,4 +43,3 @@ class String(object):
 
   def __repr__(self):
     return repr(self.__str__())
-

alphasign/text.py

@@ -9,6 +9,7 @@ class Text(object):
 
   This class is aliased as :class:`alphasign.Text` in :mod:`alphasign.__init__`.
   """
+
   def __init__(self, data=None, label=None, size=None,
                position=None, mode=None, priority=False):
     """

alphasign/time.py

@@ -3,25 +3,25 @@ from packet import Packet
 
 
 class Time(object):
+  """Class for setting and accessing the time."""
+
   def call(self):
     """Call time for insertion into a TEXT file.
 
-    Returns:
-      formatted string to use in a TEXT
+    :returns: formatted string to use in a TEXT
+    :rtype: string
     """
     return "\x13"
 
   def set(self, hour=None, minute=None):
-    """Sets ths hour and minute of the internal clock on the sign.
+    """Sets the hour and minute of the internal clock on the sign.
 
     If the time is not specified in the arguments, the time now will be used.
 
-    Args:
-      hour: hour in 24-hour format (18 instead of 6 for 6PM)
-      minute: minute (0 - 59)
+    :param hour: hour in 24-hour format (18 instead of 6 for 6PM)
+    :param minute: minute (0 - 59)
 
-    Returns:
-      Packet object
+    :rtype: :class:`alphasign.packet.Packet` object
     """
     now = datetime.datetime.today()
     if hour is None:
@@ -36,12 +36,10 @@ class Time(object):
   def set_format(self, format=1):
     """Sets the time format on the sign.
 
-    Args:
-      format: 1 - 24-hour (military) time
-              0 - 12-hour (standard am/pm) format
+    :param format: 1 - 24-hour (military) time;
+                   0 - 12-hour (standard AM/PM) format
 
-    Returns:
-      Packet object
+    :rtype: :class:`alphasign.packet.Packet` object
     """
     if format < 0 or format > 1:
       format = 1

docs/index.rst

@@ -2,7 +2,7 @@ alphasign API
 =============
 
 The alphasign package is a Python API for the
-`Alpha Communications Protocol <http://www.alpha-american.com/p-alpha-communications-protocol.html>`_.
+`Alpha Communications Protocol <http://www.alpha-american.com/p-alpha-communications-protocol.html>`_. This is the protocol used by many LED signs, including the popular `Betabrite <http://www.betabrite.com>`_. This package provides a simple and powerful way to program those signs with Python.
 
 .. automodule:: alphasign
   :members: