Add API Docs for lib/spack/llnl (#3982)

* Add API Docs for lib/spack/llnl
* Clean up after previous builds
* Better fix for purging API docs

1 files changed, 41 insertions, 27 deletions

diff --git a/lib/spack/llnl/util/tty/color.py b/lib/spack/llnl/util/tty/color.py
index b0c00f1502..bb1563f82b 100644
--- a/lib/spack/llnl/util/tty/color.py
+++ b/lib/spack/llnl/util/tty/color.py
@@ -23,39 +23,45 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 ##############################################################################
 """
-This file implements an expression syntax, similar to printf, for adding
+This file implements an expression syntax, similar to ``printf``, for adding
 ANSI colors to text.
 
-See colorize(), cwrite(), and cprint() for routines that can generate
-colored output.
+See ``colorize()``, ``cwrite()``, and ``cprint()`` for routines that can
+generate colored output.
 
-colorize will take a string and replace all color expressions with
-ANSI control codes.  If the isatty keyword arg is set to False, then
+``colorize`` will take a string and replace all color expressions with
+ANSI control codes.  If the ``isatty`` keyword arg is set to False, then
 the color expressions will be converted to null strings, and the
 returned string will have no color.
 
-cwrite and cprint are equivalent to write() and print() calls in
-python, but they colorize their output.  If the stream argument is
-not supplied, they write to sys.stdout.
+``cwrite`` and ``cprint`` are equivalent to ``write()`` and ``print()``
+calls in python, but they colorize their output.  If the ``stream`` argument is
+not supplied, they write to ``sys.stdout``.
 
 Here are some example color expressions:
 
-  @r         Turn on red coloring
-  @R         Turn on bright red coloring
-  @*{foo}    Bold foo, but don't change text color
-  @_{bar}    Underline bar, but don't change text color
-  @*b        Turn on bold, blue text
-  @_B        Turn on bright blue text with an underline
-  @.         Revert to plain formatting
-  @*g{green} Print out 'green' in bold, green text, then reset to plain.
-  @*ggreen@. Print out 'green' in bold, green text, then reset to plain.
+==========  ============================================================
+Expression  Meaning
+==========  ============================================================
+@r          Turn on red coloring
+@R          Turn on bright red coloring
+@*{foo}     Bold foo, but don't change text color
+@_{bar}     Underline bar, but don't change text color
+@*b         Turn on bold, blue text
+@_B         Turn on bright blue text with an underline
+@.          Revert to plain formatting
+@*g{green}  Print out 'green' in bold, green text, then reset to plain.
+@*ggreen@.  Print out 'green' in bold, green text, then reset to plain.
+==========  ============================================================
 
 The syntax consists of:
 
-  color-expr    = '@' [style] color-code '{' text '}' | '@.' | '@@'
-  style         = '*' | '_'
-  color-code    = [krgybmcwKRGYBMCW]
-  text          = .*
+==========  =================================================
+color-expr  '@' [style] color-code '{' text '}' | '@.' | '@@'
+style       '*' | '_'
+color-code  [krgybmcwKRGYBMCW]
+text        .*
+==========  =================================================
 
 '@' indicates the start of a color expression.  It can be followed
 by an optional * or _ that indicates whether the font should be bold or
@@ -82,6 +88,7 @@ class ColorParseError(Exception):
     def __init__(self, message):
         super(ColorParseError, self).__init__(message)
 
+
 # Text styles for ansi codes
 styles = {'*': '1',       # bold
           '_': '4',       # underline
@@ -118,8 +125,8 @@ class match_to_ansi(object):
             return ''
 
     def __call__(self, match):
-        """Convert a match object generated by color_re into an ansi color code
-           This can be used as a handler in re.sub.
+        """Convert a match object generated by ``color_re`` into an ansi
+        color code. This can be used as a handler in ``re.sub``.
         """
         style, color, text = match.groups()
         m = match.group(0)
@@ -147,10 +154,17 @@ class match_to_ansi(object):
 
 
 def colorize(string, **kwargs):
-    """Take a string and replace all color expressions with ANSI control
-       codes.  Return the resulting string.
-       If color=False is supplied, output will be plain text without
-       control codes, for output to non-console devices.
+    """Replace all color expressions in a string with ANSI control codes.
+
+    Args:
+        string (str): The string to replace
+
+    Returns:
+        str: The filtered string
+
+    Keyword Arguments:
+        color (bool): If False, output will be plain text without control
+            codes, for output to non-console devices.
     """
     color = kwargs.get('color', True)
     return re.sub(color_re, match_to_ansi(color), string)