modified a bunch of docstrings and fixed up the arguments for ensure_dir and ensure_file

docs

@@ -1 +1 @@
-Subproject commit 697af1a3153808dbffd87c415b9619ea59788696
+Subproject commit 08a9039d75dbf22afa0b8f02cef9d263fedf6e73

modules/utils.py

@@ -11,18 +11,38 @@ from fabric.operations import run, sudo
 
 
 def printvar(name, value, exit=False):
+    """
+    debug helper method to print a variable from within a process
+
+    :parameter name: name of the variable we are printing out
+    :type name: string
+
+    :parameter value: the value of the variable we want to print
+    :type value: string
+
+    :parameter exit: determines whether or not we exit the program at
+        this point. defaults to false
+    :type exit: boolean
+    """
     print("%s : %s" % (name, value))
     if exit:
         sys.exit()
 
 
 def printerr(message="", errcode=-2, exit=True):
-    """ prints error message and error code then exits
+    """
+    debug helper method thats prints error message and error code then exits
 
-    Keyword Arguments:
+    :parameter message: the error message we want to print out.
-        message -- error message
+        defaults to empty string.
-        errcode -- the error code
+    :type message: string
-        exit -- if we do a sys.exit
+
+    :parameter errcode: the code of the error
+    :type errcode: integer
+
+    :parameter exit: determines whether or not we exit the program at
+        this point. defaults to True
+    :type exit: boolean
     """
 
     message = "Error\n\t{message}\n\tExiting with code: {errcode}\n".format(
@@ -40,11 +60,17 @@ def loggify(module, func, prefix=""):
     decided to just dump it here, and return a logger that can be used and
     thrown away when it's done
 
-    module - name of the module being used, ie 'nginx', 'deploy', etc
+    :parameter module: name of the module being used, ie 'nginx', 'deploy', etc
-    func - the name of the function this logger is going to be used in
+    :type module: string
-    prefix - anything you want to add to the front of the logger, ie '\n'
 
-    returns a logging object
+    :parameter func: the name of the function this logger is going to be used
+        in
+    :type func: string
+
+    :parameter prefix: anything you want to add to the front of the logger,
+        ie \'\\n\'. defaults to an empty string.
+    :type prefix: string
+    :rtype: logging object
     """
 
     loggername = '{module}.{func}'.format(
@@ -66,12 +92,21 @@ def print_console(string, prepend="\n\n", append="\n\n", sep="-", numsep=44):
     helper function to take a string, and format it so it prints to the console
     in a way that is pleasing to the eye.
 
-    string - the string to be printed
+    :parameter string: the string to be printed
-    prepend     - defaults to two line spaces, can be anything
+    :type string: string
-    append      - defaults to two lines spaces after the string is printed
+
-    sep         - the character used to print out one line above the string and
+    :parameter prepend: defaults to two line spaces, can be anything
-                    one line after
+    :type string: string
-    numsep      - number of times the separator is printed out on a line
+
+    :parameter append: defaults to two lines spaces after the string is printed
+    :type append: string
+
+    :parameter sep: the character used to print out one line above the string
+        and one line after
+    :type sep: character
+
+    :parameter numsep: number of times the separator is printed out on a line
+    :type numsep: integer
     """
 
     print(prepend)
@@ -88,30 +123,48 @@ def print_console(string, prepend="\n\n", append="\n\n", sep="-", numsep=44):
 
 
 def print_debug(debugstr, module, function):
+    """
+    debug helper method to print out a debug string, the name of the module,
+    and the function it is located in.
+
+    The message will be printed out in the form <debugstr>:<module>:<function>
+
+    :parameter debugstr: the debugging message we want to print
+    :type debugstr: string
+
+    :parameter module: the name of the module we are in
+    :type module: string
+
+    :parameter function: the name of the function we are in
+    :type function:
+    """
+
     print("%s:%s:%s" % (module, function, debugstr))
 
 
-def executize(config_execute):
+def executize(config_execute='local'):
     """
-    A couple of times using fabric I've found that I'll need to switch between
+    creates an executor to run commands. returns one of the following methods
-    sudo, run or local depending on where I'm executing the function, because
+    fabric.api.local, fabric.operations.run or fabric.operations.sudo
-    repeating this code in every funcion that needs it can be straingint on the
-    eyes, I'm putting it here for use.
 
-    config_execute - a string that can represent the value of 'sudo',
+    :parameter config_execute: values can be either 'sudo', 'run', or 'local'.
-        'run', or 'local'
+        defaults to 'local'.
+    :type config_execute: string
 
-    return the fabric command corresponding to the string value
+    :return: the fabric command corresponding to the string value
-        in config_execute
+        in config_execute, either a sudo, a run or a local executor
     """
 
-    _execute = local
     if config_execute == 'sudo':
         _execute = sudo
     elif config_execute == 'run':
         _execute = run
     elif config_execute == 'local':
         _execute = local
+    else:
+        errmsg = "did not enter a correct value of 'sudo', 'run' or" \
+            " 'local' to executize.\nExiting."
+        printerr(message=errmsg, errcode=-2)
 
     return _execute
 
@@ -120,8 +173,16 @@ def booleanize(value):
     """
     take the argument and return it as either True or False
 
-    if the argument is neither, return False by default and warn the user that
+    if the argument is neither, throw a TypeError explaining that the value
-    there is a problem
+    given cannot be booleanized
+
+    :parameter value: takes values of y, n, yes, no, true, false,
+        1 or 0
+    :type value: string
+
+    :return: converts value to True or False.  Note 1 is
+        considered True and 0 is False
+    :rtype: boolean
     """
 
     true_values = ("y", "yes", "true", "1")
@@ -139,28 +200,38 @@ def booleanize(value):
     raise TypeError("Cannot booleanize ambiguous value '%s'" % value)
 
 
-def ensure_dir(directory):
+def ensure_dir(dirpath):
     """
-    Create a directory if it's not exists
+    Create a directory if it does not exists.
+
+    Raises an OSError if there is a problem
+
+    :parameter dirpath: directory path
+    :type dirpath: string
+
     """
     try:
-        if not os.path.exists(directory):
+        if not os.path.exists(dirpath):
-            print("creating directory: %s" % directory)
+            print("creating directory: %s" % dirpath)
-            os.makedirs(directory)
+            os.makedirs(dirpath)
 
     except OSError as e:
         if e.errno != errno.EEXIST:
             print("Error occurred while creating directory: %s"
-                  % directory)
+                  % dirpath)
             raise
 
 
-def ensure_file(f):
+def ensure_file(filepath):
     """
     Simulates linux 'touch' command
+
+    :parameter filepath: name of the file we want to create. Note this
+        must include the full path and filename
+    :type filepath: string
     """
-    if not os.path.exists(f):
+    if not os.path.exists(filepath):
-        open(f, 'w').close()
+        open(filepath, 'w').close()
 
 
 def upload_template(filename, destination, context, use_jinja,
@@ -277,9 +348,11 @@ def generate_template_files_path(section):
     """
     helper function to automate creation of build path
 
-    section - the template section we are building off of
+    :parameter section: the template section we are building off of
+    :type section: string
 
-    returns a path to where the template jinja file is located
+    :return: a path to where the template jinja file is located
+    :rtype: string
     """
     import os
 
@@ -296,12 +369,23 @@ def generate_template_files_path(section):
 
 def print_run(command, prefix="\"\n\t", suffix="\n\t\""):
     """
-    helper function for when I want a string that has the form
+    helper function to print out what a command will actually look like when
+    run
 
-    "\n\t run(some_command_string) \t\n"
+    :parameter command: a typical bash command that I want to run
+    :type command: string
 
-    where "somce_command_string" is a bash script commmand or something like
+    :parameter prefix: prefix that is added to the string, typically done
-    that
+        for clarity of viewing
+    :type prefix: string
+
+    :parameter suffix: suffix that is added to the string, typically done
+        for clarity of viewing
+    :type suffix: string
+
+    :returns: an example of how the command will actually look if run
+        on the command line
+    :rtype: string
     """
 
     return "run ({prefix}{command}{suffix})".format(