updated doc files

modules/utils.py

@@ -337,12 +337,22 @@ def get_upload_template_msg(filename, destination, context, use_jinja,
 
 @_contextmanager
 def virtualenv_source():
+    """
+    helper method that sources the virtualenvwrapper for all following commands
+
+    uses python yield command
+    """
     with prefix("source virtualenvwrapper.sh"):
         yield
 
 
 @_contextmanager
 def virtualenv():
+    """
+    helper method to set the virtual environment for the following commands
+
+    uses python yield command
+    """
     configuration = env.config
     with virtualenv_source():
         with prefix("workon %s" % configuration.virtualenv.name):
@@ -485,12 +495,20 @@ def link_create(path_src, path_dst, debug=False):
     """
     takes a source and destination path, then links it
     if the destination path already exists and is a link,
-    then delete it.  Otherwise sys.exit
+    then delete it.
 
-    path_src - source path
-    path_dst - destination path
+    Otherwise sys.exit with an error message.
 
-    returns: if debug=True then it returns a msg
+    :parameter path_src: source path
+    :type path_src: string
+
+    :paramter path_dst: destination path
+    :type path_dst: string
+
+    :parameter debug: whether we do nothing and just return a message
+    :type debug: boolean
+
+    :return: if debug=True then it returns a msg
     """
 
     from fabric.contrib.files import is_link
@@ -531,12 +549,18 @@ def link_create(path_src, path_dst, debug=False):
 
 def prompt_continue(message="Do you want to continue? Y/n", default="Y",
                     exit=True):
-    """ prompts user if he wants to continue
+    """
+    prompts user if he wants to continue
 
-    Keyword Arguments:
+    :parameter message: ask if user wants to continue
+    :type message: string
 
-        message -- ask if user wants to continue
-        default -- what to do if the user hits enter without giving a value
+    :parameter default: the default entry that we expect for the user if he
+        hits <enter> enter without giving a value
+    :type default: string
+
+    :parameter exit: whether we do a sys.exit if it fails. default True
+    :type exit: boolean
     """
 
     from fabric.operations import prompt
@@ -560,6 +584,16 @@ def prompt_continue(message="Do you want to continue? Y/n", default="Y",
 
 
 def check_debug(env):
+    """
+    helper method to determine if debug was set to True in the fabric
+    environment
+
+    :parameter env: the fabric environment
+    :type env: dict
+
+    :return: True if debug was set
+    :rtype: boolean
+    """
 
     if hasattr(env, 'debug'):
         return env.debug