[tor-commits] [stem/master] Revised API docs for stem.util.term

[atagar at torproject.org]

commit 6de23cdc3fb45eb9493c9d3819585f414fecb9cf
Author: Damian Johnson <atagar at torproject.org>
Date:   Sat Oct 27 15:49:06 2012 -0700

    Revised API docs for stem.util.term
---
 docs/api.rst       |    1 +
 docs/contents.rst  |    1 +
 docs/util/term.rst |    5 +++++
 stem/util/term.py  |   27 +++++++++++++++++++++++++--
 4 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 9a9cc0d..e63c2c2 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -31,4 +31,5 @@ Utilities
 * `stem.util.proc <util/proc.html>`_ - Tools to read a process' proc contents.
 * `stem.util.str_tools <util/str_tools.html>`_ - String utilities.
 * `stem.util.system <util/system.html>`_ - Tools related to the local system.
+* `stem.util.term <util/term.html>`_ - Tools for interacting with the terminal.
 
diff --git a/docs/contents.rst b/docs/contents.rst
index c2eb3a5..560c14a 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -27,4 +27,5 @@ Contents
    util/proc
    util/str_tools
    util/system
+   util/term
 
diff --git a/docs/util/term.rst b/docs/util/term.rst
new file mode 100644
index 0000000..d9223f4
--- /dev/null
+++ b/docs/util/term.rst
@@ -0,0 +1,5 @@
+Terminal Utilities
+==================
+
+.. automodule:: stem.util.term
+
diff --git a/stem/util/term.py b/stem/util/term.py
index 556b481..1c97989 100644
--- a/stem/util/term.py
+++ b/stem/util/term.py
@@ -1,5 +1,26 @@
 """
 Utilities for working with the terminal.
+
+**Module Overview:**
+
+::
+
+  Color - enumeration for terminal colors
+    |- BLACK
+    |- BLUE
+    |- CYAN
+    |- GREEN
+    |- MAGENTA
+    |- RED
+    |- WHITE
+    +- YELLOW
+  
+  Attr - enumeration of terminal text attributes
+    |- BOLD
+    |- HILIGHT
+    +- UNDERLINE
+  
+  format - wrap text with ANSI for the given colors or attributes
 """
 
 import stem.util.enum
@@ -30,9 +51,11 @@ def format(msg, *attr):
   * `colorama <http://pypi.python.org/pypi/colorama>`_
   
   :param str msg: string to be formatted
-  :param str attr: text attributes, this can be Color, BgColor, or Attr enums and are case insensitive (so strings like "red" are fine)
+  :param str attr: text attributes, this can be Color, BgColor, or Attr enums
+    and are case insensitive (so strings like "red" are fine)
   
-  :returns: string wrapped with ANSI escape encodings, starting with the given attributes and ending with a reset
+  :returns: **str** wrapped with ANSI escape encodings, starting with the given
+    attributes and ending with a reset
   """
   
   # if we have reset sequences in the message then apply our attributes