Improved styles.py documentation.

Author: kmvanbrunt

cmd2/styles.py

@@ -1,8 +1,27 @@
 """Defines custom Rich styles and their corresponding names for cmd2.
 
-This module provides a centralized and discoverable way to manage Rich styles used
-within the cmd2 framework. It defines a StrEnum for style names and a dictionary
-that maps these names to their default style objects.
+This module provides a centralized and discoverable way to manage Rich styles
+used within the cmd2 framework. It defines a StrEnum for style names and a
+dictionary that maps these names to their default style objects.
+
+**Notes**
+
+Cmd2 uses Rich for its terminal output, and while this module defines a set of
+cmd2-specific styles, it's important to understand that these aren't the only
+styles that can appear. Components like Rich tracebacks and the rich-argparse
+library, which cmd2 uses for its help output, also apply their own built-in
+styles. Additionally, app developers may use other Rich objects that have
+their own default styles.
+
+For a complete theming experience, you can create a custom theme that includes
+styles from Rich and rich-argparse. The `cmd2.rich_utils.set_theme()` function
+automatically updates rich-argparse's styles with any custom styles provided in
+your theme dictionary, so you don't have to modify them directly.
+
+You can find Rich's default styles in the `rich.default_styles` module.
+For rich-argparse, the style names are defined in the
+`rich_argparse.RichHelpFormatter.styles` dictionary.
+
 """
 
 import sys
@@ -26,7 +45,7 @@ class Cmd2Style(StrEnum):
     Using this enum allows for autocompletion and prevents typos when
     referencing cmd2-specific styles.
 
-    This StrEnum is tightly coupled with DEFAULT_CMD2_STYLES. Any name
+    This StrEnum is tightly coupled with `DEFAULT_CMD2_STYLES`. Any name
     added here must have a corresponding style definition there.
     """