Updated Sphinx documentation and README.md

Author: tleonhardt

README.md

@@ -43,6 +43,7 @@ Main Features
 - Built-in regression testing framework for your applications (transcript-based testing)
 - Transcripts for use with built-in regression can be automatically generated from `history -t` or `run_script -t`
 - Alerts that seamlessly print while user enters text at prompt
+- Colored and stylized output using `ansi.style()`
 
 Python 2.7 support is EOL
 -------------------------
@@ -89,7 +90,7 @@ Instructions for implementing each feature follow.
     class MyApp(cmd2.Cmd):
         def do_foo(self, args):
             """This docstring is the built-in help for the foo command."""
-            print('foo bar baz')
+            print(cmd2.ansi.style('foo bar baz', fg='red'))
     ```
     - By default the docstring for your **do_foo** method is the help for the **foo** command
         - NOTE: This doesn't apply if you use one of the `argparse` decorators mentioned below
@@ -314,11 +315,10 @@ example/transcript_regex.txt:
 
 ```text
 # Run this transcript with "python example.py -t transcript_regex.txt"
-# The regex for colors is because no color on Windows.
 # The regex for editor will match whatever program you use.
 # regexes on prompts just make the trailing space obvious
 (Cmd) set
-colors: /(True|False)/
+allow_ansi: Terminal
 continuation_prompt: >/ /
 debug: False
 echo: False
@@ -331,9 +331,7 @@ quiet: False
 timing: False
 ```
 
-Note how a regular expression `/(True|False)/` is used for output of the **show color** command since
-colored text is currently not available for cmd2 on Windows.  Regular expressions can be used anywhere within a
-transcript file simply by enclosing them within forward slashes, `/`.
+Regular expressions can be used anywhere within a transcript file simply by enclosing them within forward slashes, `/`.
 
 
 Found a bug?

cmd2/ansi.py

@@ -132,17 +132,17 @@ def bg_lookup(bg_name: str) -> str:
 
 
 def style(text: Any, *, fg: str = '', bg: str = '', bold: bool = False, underline: bool = False) -> str:
-    """
-    Applies styles to text
+    """Styles a string with ANSI colors and/or styles and returns the new string.
+
+    The styling is self contained which means that at the end of the string reset code(s) are issued
+    to undo whatever styling was done at the beginning.
 
     :param text: Any object compatible with str.format()
     :param fg: foreground color. Expects color names in FG_COLORS (e.g. 'red'). Defaults to no color.
     :param bg: background color. Expects color names in BG_COLORS (e.g. 'black'). Defaults to no color.
     :param bold: apply the bold style if True. Defaults to False.
     :param underline: apply the underline style if True. Defaults to False.
-
     :return: the stylized string
-    :raises ValueError if fg or bg color does cannot be found
     """
     # List of strings that add style
     additions = []

docs/unfreefeatures.rst

@@ -141,7 +141,7 @@ instead.  These methods have these advantages:
 Colored Output
 ==============
 
-The output methods in the previous section all honor the ``colors`` setting,
+The output methods in the previous section all honor the ``allow_ansi`` setting,
 which has three possible values:
 
 Never
@@ -152,14 +152,17 @@ Terminal
     (the default value) poutput(), pfeedback(), and ppaged() do not strip any
     ANSI escape sequences when the output is a terminal, but if the output is
     a pipe or a file the escape sequences are stripped. If you want colorized
-    output you must add ANSI escape sequences, preferably using some python
-    color library like `plumbum.colors`, `colorama`, `blessings`, or
-    `termcolor`.
+    output you must add ANSI escape sequences using either cmd2's internal ansi
+    module or another color library such as `plumbum.colors`, `colorama`, or `colored`.
 
 Always
     poutput(), pfeedback(), and ppaged() never strip ANSI escape sequences,
     regardless of the output destination
 
+Colored and otherwise styled output can be generated using the `ansi.style()` function:
+
+.. automethod:: cmd2.ansi.style
+
 
 .. _quiet: