Update Documentation

*   Move all documentation out of Task Reference
    Use ``autofunction`` to include the docstring of the appropriate
    function

*   Update docstrings of all functions in ``xnt.tasks``, ``xnt.build``,
    ``xnt.vcs``

8 files changed, 182 insertions, 123 deletions

diff --git a/docs/source/taskreference.rst b/docs/source/taskreference.rst
index 2ffbfcb..16c41b5 100644
--- a/docs/source/taskreference.rst
+++ b/docs/source/taskreference.rst
@@ -20,92 +20,47 @@ Overview of Tasks
 File Tasks
 ==========
 
-.. _xnt.tasks.expandpath:
-.. function:: expandpath(path)
+.. autofunction:: xnt.tasks.expandpath
+   :noindex:
 
-    Return a generator for glob expansion of *path*
+.. autofunction:: xnt.tasks.cp
+   :noindex:
 
-.. _xnt.tasks.cp:
-.. function:: cp(src="", dst="", files=None)
+.. autofunction:: xnt.tasks.mv
+   :noindex:
 
-    Copy the source file or directory (*src*) OR files/folders (*files*) to
-    destination file or directory (*dst*)
+.. autofunction:: xnt.tasks.mkdir
+   :noindex:
 
-.. _xnt.tasks.mv:
-.. function:: mv(src, dst)
-
-    Move the source file or directory (*src*) to destination file or
-    directory (*dst*)
-
-.. _xnt.tasks.mkdir:
-.. function:: mkdir(dir, mode=0o777)
-
-    Create a directory specified by *dir* with default mode (where supported)
-    or with the specified mode
-
-    Notice, if the directory already exists, *mkdir* will not attempt to
-    create it again (or change the mode)
-
-.. _xnt.tasks.rm:
-.. function:: rm(*fileset)
-
-    Attempt to remove all the directories given in fileset. Before *rm* tries
-    to delete each element of fileset, it attempts to expand it first, thus
-    allowing the passing of glob elements.
+.. autofunction:: xnt.tasks.rm
+   :noindex:
 
 Archive Tasks
 =============
 
-.. _xnt.tasks.create_zip:
-.. function:: create_zip(directory, zipfilename)
-
-    Zip the specified *directory* into the zip file specified by *zipfilename*
+.. autofunction:: xnt.tasks.create_zip
+   :noindex:
 
 Miscellaneous Tasks
 ===================
 
-.. _xnt.tasks.echo:
-.. function:: echo(msg, tofile)
-
-    Write the given message to a file
-
-    *echo* will handle opening and closing the file
-
-.. _xnt.tasks.log:
-.. function:: log(msg="", lvl=logging.INFO)
-
-    Write the message (*msg*) to the *xnt.tasks* logger using either the
-    default log level (*INFO*) or any other valid specified value
-
-.. _xnt.tasks.call:
-.. function:: call(command, stdout=None, stderr=None)
+.. autofunction:: xnt.tasks.echo
+   :noindex:
 
-    Invoke the command specified, redirecting standard output and standard
-    error as specified.
+.. autofunction:: xnt.tasks.log
+   :noindex:
 
-    *command* must be in the form of a list for :mod:`subprocess`
+.. autofunction:: xnt.tasks.call
+   :noindex:
 
-    *stdout* and *stderr* must be an open file handle. [However, that may
-    change; I'm not sure how I feel about that yet.]
-
-.. _xnt.tasks.xntcall:
-.. function:: xntcall(buildfile, targets=None, props=None)
-
-    Invoke the *target(s)* of a build file in a different *path*.
-
-    *target* is the name of the target to invoke (similar to *target* of a
-    regular invocation.
-
-    *buildfile* is the path (relative or full) and build file to use
+.. autofunction:: xnt.tasks.xntcall
+   :noindex:
 
 Compile Tasks
 =============
 
-.. _xnt.tasks.setup:
-.. function:: setup(commands, directory="")
-
-    Invoke Python setup.py given the list of *commands* (or options) in the
-    current directory or in a different directory, specified by *directory*.
+.. autofunction:: xnt.tasks.setup
+   :noindex:
 
 SCM Tasks
 =========
@@ -115,54 +70,30 @@ SCM Tasks
 Mercurial Tasks
 ---------------
 
-.. _xnt.vcs.hg.hgclone:
-.. function:: hgclone(url, dest=None, rev=None, branch=None)
-
-    Clone the Mercurial repository at *url* (This can be any valid URI, Local,
-    SSH, HTTP(S)...) into either the default destination or a specified
-    directory (relative to the current working directory).
+.. autofunction:: xnt.vcs.hg.hgclone
+   :noindex:
 
-    *rev* and *branch* can be used to clone a specific revision or a specific
-    branch of the repository, respectively.
-
-.. _xnt.vcs.hg.hgfetch:
-.. function:: hgfetch(path, source='default')
-
-    Fetch any updates from either the default source or a specified source for
-    the repository specified by *path*
+.. autofunction:: xnt.vcs.hg.hgfetch
+   :noindex:
 
 .. _xnt.vcs.git:
 
 Git Tasks
 ---------
 
-.. _xnt.vcs.git.gitclone:
-.. function:: gitclone(url, dest=None, branch=None)
-
-    Clone the Git repository at *url* (This can be any valid URI: Local, SSH,
-    Git, HTTP(S)...) into either the default destination or specified directory
-    (relative to the current working directory).
+.. autofunction:: xnt.vcs.git.gitclone
+   :noindex:
 
-.. _xnt.vcs.git.gitpull:
-.. function:: gitpull(path, source="origin", branch="master")
-
-    Pull any updates from either the default source and/ or specified branch
-    into the existing Git repository located at *path*.
+.. autofunction:: xnt.vcs.git.gitpull
+   :noindex:
 
 .. _xnt.vcs.cvs:
 
 CVS Tasks
 ---------
 
-.. _xnt.vcs.cvs.cvsco:
-.. function:: cvsco(module, rev="", dest="")
-
-    Checkout the CVS module specified by *module*; getting the HEAD revision or
-    any valid revision specified by *rev* and putting it into the default
-    directory or the specified directory, *dest* (relative to the current
-    working directory).
-
-.. _xnt.vcs.cvs.cvsupdate:
-.. function:: cvsupdate(path)
+.. autofunction:: xnt.vcs.cvs.cvsco
+   :noindex:
 
-    Update the CVS module located at *path*.
+.. autofunction:: xnt.vcs.cvs.cvsupdate
+   :noindex:
diff --git a/xnt/build/cc.py b/xnt/build/cc.py
index 7dedeb5..5cb455f 100644
--- a/xnt/build/cc.py
+++ b/xnt/build/cc.py
@@ -27,23 +27,45 @@ from xnt.tasks import call
 LOGGER = logging.getLogger(__name__)
 
 def gcc(src, flags=None):
-    """gcc compiler, non-named output file"""
+    """gcc compiler, non-named output file
+
+    :param src: C source file to compile with default `gcc`
+    :param flags: List of flags to pass onto the compiler
+    """
     return _gcc(src, flags)
 
 def gpp(src, flags=None):
-    """g++ compiler, non-named output file"""
+    """g++ compiler, non-named output file
+
+    :param src: C++ source file to compile with default `g++`
+    :param flags: List of flags to pass onto the compiler
+    """
     return _gcc(src, flags, "g++")
 
 def gcc_o(src, output, flags=None):
-    """gcc compiler, with output file"""
+    """gcc compiler, with output file
+
+    :param src: C source file to compile with default `gcc`
+    :param output: Name of resulting object or executable
+    :param flags: List of flags to pass onto the compiler
+    """
     return _gcc_o(src, output, flags)
 
 def gpp_o(src, output, flags=None):
-    """g++ compiler, with output file"""
+    """g++ compiler, with output file
+
+    :param src: C++ source file to compile with default `g++`
+    :param output: Name of resulting object or executable
+    :param flags: List of flags to pass onto the compiler
+    """
     return _gcc_o(src, output, flags, "g++")
 
 def javac(src, flags=None):
-    """Javac: compile Java programs"""
+    """Javac: compile Java programs
+
+    :param src: Java source file to compile with default `javac`
+    :param flags: List of flags to pass onto the compiler
+    """
     LOGGER.info("Compiling %s", src)
     cmd = __generate_command(src, flags, "javac")
     return __compile(cmd)
diff --git a/xnt/build/make.py b/xnt/build/make.py
index 74dcf49..df4fb85 100644
--- a/xnt/build/make.py
+++ b/xnt/build/make.py
@@ -21,7 +21,17 @@ import os
 import subprocess
 
 def ant(target, path="", flags=None, pkeys=None, pvalues=None):
-    """Wrapper around Apache Ant"""
+    """Wrapper around Apache Ant
+
+    `pkeys` and `pvalues` are zipped to form a key/value pair passed to Ant as
+    property values
+
+    :param target: Ant Target to execute
+    :param path: Path of the Ant build file if different than current directory
+    :param flags: List of flags to pass to Ant
+    :param pkeys: List of keys to combine with pvalues to pass to Ant
+    :param pvalues: List of values to combine with pkeys to pass to Ant
+    """
     cmd = __add_params(["ant"],
                        __build_param_list(pkeys, pvalues),
                        lambda x: "-D%s" % x)
@@ -30,14 +40,34 @@ def ant(target, path="", flags=None, pkeys=None, pvalues=None):
     return __run_in(path, lambda: subprocess.call(cmd))
 
 def make(target, path="", flags=None, pkeys=None, pvalues=None):
-    """Wrapper around GNU Make"""
+    """Wrapper around GNU Make
+
+    `pkeys` and `pvalues` are zipped together to form a key/value pair that are
+    passed to Make as property values.
+
+    :param target: Make Target to execute
+    :param path: Path of the make file if different than current directory
+    :param flags: List of flags to pass to make
+    :param pkeys: List of keys, zipped with pvalues, to pass to Make
+    :param pvalues: List of values, zipped with pkeys, to pass to Make
+    """
     cmd = __add_params(["make"], __build_param_list(pkeys, pvalues))
     cmd = __add_flags(cmd, flags)
     cmd.append(target)
     return __run_in(path, lambda: subprocess.call(cmd))
 
 def nant(target, path="", flags=None, pkeys=None, pvalues=None):
-    """Wrapper around .NET Ant"""
+    """Wrapper around .NET Ant
+
+    `pkeys` and `pvalues` are zipped together to form a key/ value pair to pass
+    to NAnt as property values.
+
+    :param target: NAnt Target to execute
+    :param path: Path of NAnt build file, if different than current directory
+    :param flags: List of flags to pass to NAnt
+    :param pkeys: List of keys, zipped with pvalues, to pass to NAnt
+    :param pvalues: List of values, zipped with pkeys, to pass to NAnt
+    """
     cmd = __add_params(["nant"],
                         __build_param_list(pkeys, pvalues),
                         lambda x: "-D:%s" % x)
diff --git a/xnt/build/tex.py b/xnt/build/tex.py
index 15bb6fb..f5e6396 100644
--- a/xnt/build/tex.py
+++ b/xnt/build/tex.py
@@ -28,7 +28,13 @@ def pdflatex(document,
              path="./",
              bibtex=False,
              makeglossary=False):
-    """Generate PDF LaTeX Document"""
+    """Generate PDF LaTeX Document
+
+    :param document: Name of tex file (with or without `.tex` extension)
+    :param path: Directory of tex file, if different than current directory
+    :param bibtex: Flag to or not to add bibtex. Default: False
+    :param makeglossary: Flag to or not to add a glossary. Default: False
+    """
     devnull = None if VERBOSE else open(os.devnull, 'w')
     documentbase = os.path.splitext(document)[0]
     cwd = os.getcwd()
@@ -63,7 +69,11 @@ def pdflatex(document,
     return sum(error_codes)
 
 def clean(path="./", remove_pdf=False):
-    """Clean up generated files of PDF compiliation"""
+    """Clean up generated files of PDF compilation
+
+    :param path: Directory of output files, if different than current directory
+    :param remove_pdf: Flag to remove the PDF. Default: False
+    """
     cwd = os.getcwd()
     os.chdir(path)
     xnt.tasks.rm("*.out",
diff --git a/xnt/tasks.py b/xnt/tasks.py
index c32193d..fcf7a9a 100644
--- a/xnt/tasks.py
+++ b/xnt/tasks.py
@@ -33,8 +33,13 @@ import logging
 LOGGER = logging.getLogger(__name__)
 
 #File associated tasks
-def expandpath(path):
-    """Return a glob expansion generator of *path*"""
+def expandpath(path_pattern):
+    """Return a glob expansion generator of *path_pattern*
+
+    :param path_pattern: pattern to expand
+    :rtype: generator of strings
+    :return: List of paths and/ or files
+    """
     return glob.iglob(path)
 
 def cp(src="", dst="", files=None):
@@ -42,6 +47,12 @@ def cp(src="", dst="", files=None):
 
     Copy a file or folder to a different file/folder
     If no `src` file is specified, will attempt to copy `files` to `dst`
+
+    *Notice*, elements of `files` will not be expanded before copying.
+
+    :param src: source directory or file
+    :param dst: destination file or folder (in the case of `files`)
+    :param files: list of files (strings) to copy to `src`
     """
     assert dst and src or len(files) > 0
     LOGGER.info("Copying %s to %s", src, dst)
@@ -65,6 +76,9 @@ def mv(src, dst):
 
     Move (copy and remove) the source file or directory (*src*) to the
     destination file or directory (*dst*)
+
+    :param src: Source file or folder to move
+    :param dst: Destination file or folder
     """
     LOGGER.info("Moving %s to %s", src, dst)
     shutil.move(src, dst)
@@ -77,6 +91,9 @@ def mkdir(directory, mode=0o777):
 
     *Notice*, if the directory already exists, *mkdir* will log a warning and
     return
+
+    :param directory: New directory to create
+    :param mode: Mode to create the directory (where supported). Default: `777`
     """
     if os.path.exists(directory):
         LOGGER.warning("Given directory (%s) already exists", directory)
@@ -96,6 +113,8 @@ def rm(*fileset):
     tries to delete each element of *fileset*, it attempts to expand it first
     using glob expansion (:func:`xnt.tasks.expandpath`), thus allowing the
     passing of glob elements
+
+    :param fileset: List of files to remove
     """
 
     try:
@@ -117,6 +136,9 @@ def create_zip(directory, zipfilename):
     """Compress (Zip) folder
 
     Zip the specified *directory* into the zip file named *zipfilename*
+
+    :param directory: Directory to zip
+    :param zipfilename: Name of resulting compression
     """
     LOGGER.info("Zipping %s as %s", directory, zipfilename)
     assert os.path.isdir(directory) and zipfilename
@@ -137,6 +159,9 @@ def echo(msg, tofile):
     Write the given *msg* to a file named *tofile*
 
     *Notice*, `echo` will overwrite the file if it already exists
+
+    :param msg: Message to write to file
+    :param tofile: file to which the message is written
     """
     with open(tofile, "w") as file_to_write:
         file_to_write.write(msg)
@@ -146,6 +171,9 @@ def log(msg="", lvl=logging.INFO):
 
     Emit the message (*msg*) to the *xnt.tasks* logger using either the default
     log level (*INFO*) or any valid specified value of `logging` module
+
+    :param msg: Message to log
+    :param lvl: Log Level of message. Default `INFO`
     """
     LOGGER.log(lvl, msg)
 
@@ -172,6 +200,7 @@ def call(command, stdout=None, stderr=None):
     :param: command - list of command and arguments
     :param: stdout - file to redirect standard output to, if given
     :param: stderr - file to redirect standard error to, if given
+    :return: the error code of the subbed out call, `$?`
     """
     return subprocess.call(args=command, stdout=stdout, stderr=stderr)
 
@@ -180,6 +209,7 @@ def setup(commands, directory=""):
 
     :param: commands - list of commands and options to run/ append
     :param: dir - (optional) directory to run from
+    :return: the error code of the execution, `$?`
     """
     cmd = [sys.executable, "setup.py",]
     for command in commands:
@@ -192,7 +222,11 @@ def setup(commands, directory=""):
     return error_code
 
 def which(program):
-    """Similar to Linux/Unix `which`: return (first) path of executable"""
+    """Similar to Linux/Unix `which`: return (first) path of executable
+
+    :param program: program name to search for in PATH
+    :return: Return the PATH of `program` or None
+    """
     def is_exe(fpath):
         """Determine if argument exists and is executable"""
         return os.path.isfile(fpath) and os.access(fpath, os.X_OK)
@@ -210,5 +244,9 @@ def which(program):
     return None
 
 def in_path(program):
-    """Return boolean result if program is in PATH environment variable"""
+    """Return boolean result if program is in PATH environment variable
+
+    :param program: Program name to search for in PATH
+    :return: Return the PATH of `program` or None
+    """
     return which(program)
diff --git a/xnt/vcs/cvs.py b/xnt/vcs/cvs.py
index 639de99..fa596c8 100644
--- a/xnt/vcs/cvs.py
+++ b/xnt/vcs/cvs.py
@@ -21,7 +21,12 @@ import os
 import subprocess
 
 def cvsco(module, rev="", dest=""):
-    """Run CVS Checkout"""
+    """Run CVS Checkout
+
+    :param module: CVS Module name to checkout
+    :param rev: Revision to checkout
+    :param dest: Destination directory or name of checked out module
+    """
     cmd = ["cvs", "co", "-P"]
     if rev:
         cmd.append("-r")
@@ -33,7 +38,10 @@ def cvsco(module, rev="", dest=""):
     subprocess.call(cmd)
 
 def cvsupdate(path):
-    """Run CVS Update"""
+    """Run CVS Update
+
+    :param path: Directory path to module to update
+    """
     cwd = os.path.abspath(os.getcwd())
     os.chdir(path)
     cmd = ["cvs", "update"]
diff --git a/xnt/vcs/git.py b/xnt/vcs/git.py
index 7c4857d..00e2828 100644
--- a/xnt/vcs/git.py
+++ b/xnt/vcs/git.py
@@ -22,13 +22,23 @@ import xnt.tasks
 import xnt.vcs
 
 def gitclone(url, dest=None, branch=None):
-    """Clone a repository"""
+    """Clone a repository
+
+    :param url: URI of the repository to clone
+    :param dest: Destination directory or name of the cloned repository
+    :param branch: Branch to clone
+    """
     command = ["git", "clone"]
     command = xnt.vcs.clone_options(command, url, branch, dest)
     xnt.tasks.call(command)
 
 def gitpull(path, source="origin", branch="master"):
-    """Pull/Update a cloned repository"""
+    """Pull/Update a cloned repository
+
+    :param path: Directory of the repository for which to pull and update
+    :param source: Repository's upstream source
+    :param branch: Repository's upstream branch to pull from
+    """
     cwd = os.getcwd()
     os.chdir(path)
     command = ["git", "pull", source, branch]
diff --git a/xnt/vcs/hg.py b/xnt/vcs/hg.py
index b109fad..092c01d 100644
--- a/xnt/vcs/hg.py
+++ b/xnt/vcs/hg.py
@@ -22,7 +22,13 @@ import xnt.tasks
 import xnt.vcs
 
 def hgclone(url, dest=None, rev=None, branch=None):
-    """Clone a Mercurial Repository"""
+    """Clone a Mercurial Repository
+
+    :param url: URI of repository to clone
+    :param dest: Directory or name of cloned repository
+    :param rev: Revision to clone
+    :param branch: Branch to clone
+    """
     command = ["hg", "clone"]
     if rev:
         command.append("--rev")
@@ -31,7 +37,11 @@ def hgclone(url, dest=None, rev=None, branch=None):
     xnt.tasks.call(command)
 
 def hgfetch(path, source='default'):
-    """Pull and Update an already cloned Mercurial Repository"""
+    """Pull and Update an already cloned Mercurial Repository
+
+    :param path: Directory to the repository for which to pull changes
+    :param source: Repository's upstream source
+    """
     command = ["hg", "pull", "-u", source]
     cwd = os.getcwd()
     os.chdir(path)