Add a simple example to demonstrate the colors available in cmd2.Color (#1482)

Also:

- Deleted old examples/colors.py and updated documentation

---------

Co-authored-by: Kevin Van Brunt <[email protected]>

Author: tleonhardt

docs/features/completion.md

@@ -96,8 +96,7 @@ Tab completion of argument values can be configured by using one of three parame
 - `completer`
 
 See the [arg_decorators](https://github.com/python-cmd2/cmd2/blob/main/examples/arg_decorators.py)
-or [colors](https://github.com/python-cmd2/cmd2/blob/main/examples/colors.py) example for a
-demonstration of how to use the `choices` parameter. See the
+example for a demonstration of how to use the `choices` parameter. See the
 [argparse_completion](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_completion.py)
 example for a demonstration of how to use the `choices_provider` parameter. See the
 [arg_decorators](https://github.com/python-cmd2/cmd2/blob/main/examples/arg_decorators.py) or

examples/README.md

@@ -32,8 +32,8 @@ each:
     - Show how to enable custom tab completion by assigning a completer function to `do_*` commands
 - [cmd2_as_argument.py](https://github.com/python-cmd2/cmd2/blob/main/examples/cmd_as_argument.py)
     - Demonstrates how to accept and parse command-line arguments when invoking a cmd2 application
-- [colors.py](https://github.com/python-cmd2/cmd2/blob/main/examples/colors.py)
-    - Show various ways of using colorized output within a cmd2 application
+- [color.py](https://github.com/python-cmd2/cmd2/blob/main/examples/color.py)
+    - Show the numerous colors available to use in your cmd2 applications
 - [custom_parser.py](https://github.com/python-cmd2/cmd2/blob/main/examples/custom_parser.py)
     - Demonstrates how to create your own custom `Cmd2ArgumentParser`
 - [decorator_example.py](https://github.com/python-cmd2/cmd2/blob/main/examples/decorator_example.py)

examples/color.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python
+"""A sample application for cmd2. Demonstrating colors available in the cmd2.colors.Color enum.
+
+Execute the taste_the_rainbow command to see the colors available.
+"""
+
+import argparse
+
+from rich.style import Style
+
+import cmd2
+from cmd2 import (
+    Color,
+    stylize,
+)
+
+
+class CmdLineApp(cmd2.Cmd):
+    """Example cmd2 application demonstrating colorized output."""
+
+    def __init__(self) -> None:
+        # Set include_ipy to True to enable the "ipy" command which runs an interactive IPython shell
+        super().__init__(include_ipy=True)
+        self.intro = 'Run the taste_the_rainbow command to see all of the colors available to you in cmd2.'
+
+    rainbow_parser = cmd2.Cmd2ArgumentParser()
+    rainbow_parser.add_argument('-b', '--background', action='store_true', help='show background colors as well')
+    rainbow_parser.add_argument('-p', '--paged', action='store_true', help='display output using a pager')
+
+    @cmd2.with_argparser(rainbow_parser)
+    def do_taste_the_rainbow(self, args: argparse.Namespace) -> None:
+        """Show all of the colors available within cmd2's Color StrEnum class."""
+
+        color_names = []
+        for color_member in Color:
+            style = Style(bgcolor=color_member) if args.background else Style(color=color_member)
+            styled_name = stylize(color_member.name, style=style)
+            if args.paged:
+                color_names.append(styled_name)
+            else:
+                self.poutput(styled_name)
+
+        if args.paged:
+            self.ppaged('\n'.join(color_names))
+
+
+if __name__ == '__main__':
+    import sys
+
+    c = CmdLineApp()
+    sys.exit(c.cmdloop())