diff options
author | kennyballou <kballou@onyx.boisestate.edu> | 2013-05-31 17:48:01 -0600 |
---|---|---|
committer | kennyballou <kballou@onyx.boisestate.edu> | 2013-05-31 17:48:01 -0600 |
commit | d121abac4f8cde0a8ef2419c6bdfb52e7c4dcb6d (patch) | |
tree | 9f5fc1f1304d603e99c7e3b3e5f1bec9ca152986 /xnt | |
parent | be52b27a68555f1731b2506ddf906b3120d98d5d (diff) | |
download | xnt-d121abac4f8cde0a8ef2419c6bdfb52e7c4dcb6d.tar.gz xnt-d121abac4f8cde0a8ef2419c6bdfb52e7c4dcb6d.tar.xz |
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``
Diffstat (limited to 'xnt')
-rw-r--r-- | xnt/build/cc.py | 32 | ||||
-rw-r--r-- | xnt/build/make.py | 36 | ||||
-rw-r--r-- | xnt/build/tex.py | 14 | ||||
-rw-r--r-- | xnt/tasks.py | 46 | ||||
-rw-r--r-- | xnt/vcs/cvs.py | 12 | ||||
-rw-r--r-- | xnt/vcs/git.py | 14 | ||||
-rw-r--r-- | xnt/vcs/hg.py | 14 |
7 files changed, 148 insertions, 20 deletions
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) |