Merge pull request #21 from laurentalacoque/documentation

Documentation

Author: laurentalacoque

scripts/configuration.py

@@ -1,7 +1,9 @@
+"""Configuration module to adapt TouchSelfie behavior"""
 import json
 import os
 
 class Configuration():
+    """Configuration class acts as configuration keys/values holder"""
     # default values
     user_name = None
     logo_file = None
@@ -20,6 +22,14 @@ class Configuration():
 
     #init
     def __init__(self,configuration_file_name):
+        """Creates the configuration object with default values and load the configuration file
+        
+        __init__ will parse the configuration file given as its argument
+        After parsing, is_valid property is set to True if no error was encountered
+        
+        Arguments:
+            configuration_file_name -- the conf.json file to read from or write to
+        """
         self.config_file = configuration_file_name
         self.is_valid = False
         self.__read_config_file()
@@ -60,6 +70,7 @@ def __read_config_file(self):
 
 
     def write(self):
+        """ write the configuration object to the configuration file given at creation time"""
         myconfig = {
             "gmail_user": self.user_name,
             "countdown_before_snap": self.countdown1,
@@ -87,4 +98,4 @@ def write(self):
 
     config = Configuration("myconf.conf")
     if not config.is_valid:
-        config.write()
+        config.write()

scripts/constants.py

@@ -1,3 +1,29 @@
+"""
+Constants for the TouchSelfie program
+
+.. py:data:: SCREEN_H,SCREEN_W
+    Dimensions in pixels of the screen attached (will be used to compute layout)
+.. py:data:: EFFECT_PARAMETERS
+    A dict of dict data structure to tune acquisition parameters for each snap effct
+.. py:data:: SOFTWARE_BUTTONS
+    A dict of dict data structure to tune software buttons (in case of no hardware buttons)
+.. py:data:: HARDWARE_BUTTONS
+    configuration of the hardware buttons' GPIO pins, pull_up_down state and active state
+.. py:data:: EMAIL_BUTTON_IMG  
+    'send_email' button icon
+.. py:data:: OAUTH2_REFRESH_PERIOD
+    interval between two OAuth2 token refresh (ms)
+.. py:data:: HARDWARE_POLL_PERIOD = 100
+    polling interval to detect hardware buttons change (ms)
+
+.. py:data:: CONFIGURATION_FILE
+    name of the configuration file (relative to scripts/ directory)
+.. py:data:: APP_ID_FILE
+    name of the 'application_secret' file downloaded from console.developers.google.com (relative to scripts/ directory)
+.. py:data:: CREDENTIALS_STORE_FILE
+    name of the automaticaly generated credentials store (relative to scripts/ directory)
+
+"""
 
 SCREEN_W = 800 ## raspi touch
 SCREEN_H = 480 ## raspi touch

scripts/hardware_buttons.py

@@ -22,18 +22,31 @@
 
 
 class Buttons():
+    """Hardware Buttons wrapper class"""
+    
     def __init__(self, buttons_pins=BUTTONS_PINS, mode=BUTTONS_MODE, active_state=BUTTON_IS_ACTIVE):
+        """Constructor for Buttons
+        
+        Arguments:
+            button_pins [list(int)]         : list of GPIO pins
+            mode ["pull_up" or "pull_down"] : the pull state of the GPIO
+            active_state [0 or 1]           : GPIO status when activated
+        
+        Note: this is safe to use this class on systems that don't have GPIO module
+            in this case, has_buttons() methods returns False
+        """
         self.buttons_pins = buttons_pins
-        if mode == "pull_up":
-            self.mode = GPIO.PUD_UP
-        elif mode == "pull_down":
-            self.mode = GPIO.PUD_DOWN
-        else:
-            raise ValueError("Unknown pull_up_down mode %s"%mode)
+
 
         self.active_state = active_state
         self._has_buttons = False
         if RPI_GPIO_EXISTS:
+            if mode == "pull_up":
+                self.mode = GPIO.PUD_UP
+            elif mode == "pull_down":
+                self.mode = GPIO.PUD_DOWN
+            else:
+                raise ValueError("Unknown pull_up_down mode %s"%mode)
             GPIO.setmode(GPIO.BOARD)
             for pin in self.buttons_pins:
                 GPIO.setup(pin, GPIO.IN, pull_up_down = self.mode)
@@ -43,16 +56,39 @@ def __init__(self, buttons_pins=BUTTONS_PINS, mode=BUTTONS_MODE, active_state=BU
                 self._has_buttons = False
 
     def __del__(self):
+        """Cleanup GPIO"""
         if self._has_buttons:
             GPIO.cleanup()
 
     def has_buttons(self):
+        """Wether buttons were configured
+        
+        returns: True if at lease one button configured
+        """
         return self._has_buttons
 
     def buttons_number(self):
+        """Number of configured hardware buttons
+        
+        returns: the number of buttons configured
+        """
         return len(self.buttons_pins)
 
     def state(self):
+        """Current state of the hardware buttons
+        
+        buttons are checked in the order provided to the constructor
+        as soon as a button state == active_state, the loop ends and the 
+        index of the active button is returned (first items of the buttons list
+        therefore have higher priority)
+        
+        returns: 
+            0 if no button currently active
+            i (i>0) the index of the first active button with:
+                i=1 => button_pins[0] is active
+                i=2 => button_pins[1] is active
+                ...
+        """
         if not self._has_buttons:
             return 0