diff --git a/docs/features/argument_processing.md b/docs/features/argument_processing.md index 9535d5e21..5f3392d16 100644 --- a/docs/features/argument_processing.md +++ b/docs/features/argument_processing.md @@ -65,6 +65,9 @@ def do_speak(self, opts): `cmd2` sets the `prog` variable in the argument parser based on the name of the method it is decorating. This will override anything you specify in `prog` variable when creating the argument parser. +As of the 3.0.0 release, `cmd2` sets `prog` when the instance-specific parser is created, which is +later than it did previously. + ## Help Messages By default, `cmd2` uses the docstring of the command method when a user asks for help on the diff --git a/docs/features/generating_output.md b/docs/features/generating_output.md index b423258d0..b9356bfe0 100644 --- a/docs/features/generating_output.md +++ b/docs/features/generating_output.md @@ -19,6 +19,11 @@ output you generate must be sent to `self.stdout`. You can use the methods descr everything will work fine. [cmd2.Cmd][] also includes a number of output related methods which you may use to enhance the output your application produces. +Since `cmd2` has a dependency on the [rich](https://github.com/Textualize/rich) library, all of +`cmd2`'s output methods can natively render `rich` +[renderable objects](https://rich.readthedocs.io/en/latest/protocol.html), enabling beautiful and +complex output. + ## Ordinary Output The `cmd2.Cmd.poutput` method is similar to the Python @@ -92,6 +97,16 @@ following sections: - [cmd2.string_utils][] - [cmd2.terminal_utils][] +The [color.py](https://github.com/python-cmd2/cmd2/blob/main/examples/color.py) example demonstrates +all colors available to your `cmd2` application. + +### Custom Themes + +`cmd2` uses a `rich` `Theme` object to define styles for various UI elements. You can define your +own custom theme using `cmd2.rich_utils.set_theme`. See the +[rich_theme.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_theme.py) example for +more information. + After adding the desired escape sequences to your output, you should use one of these methods to present the output to the user: @@ -110,9 +125,9 @@ to control whether these escape codes are passed through to the terminal or not. If you would like to generate output which is left, center, or right aligned within a specified width or the terminal width, the following functions can help: -- `cmd2.utils.align_left` -- `cmd2.utils.align_center` -- `cmd2.utils.align_right` +- `cmd2.string_utils.align_left` +- `cmd2.string_utils.align_center` +- `cmd2.string_utils.align_right` These functions differ from Python's string justifying functions in that they support characters with display widths greater than 1. Additionally, ANSI style sequences are safely ignored and do not diff --git a/docs/features/table_creation.md b/docs/features/table_creation.md index 2509ba45f..4a54cadd4 100644 --- a/docs/features/table_creation.md +++ b/docs/features/table_creation.md @@ -7,3 +7,6 @@ excellent support for this feature. Please see rich's documentation on [Tables](https://rich.readthedocs.io/en/latest/tables.html) for more information. + +The [rich_tables.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_tables.py) example +demonstrates how to use `rich` tables in a `cmd2` application. diff --git a/docs/migrating/next_steps.md b/docs/migrating/next_steps.md index a261bccfd..1e047a524 100644 --- a/docs/migrating/next_steps.md +++ b/docs/migrating/next_steps.md @@ -41,6 +41,6 @@ If your program generates output by printing directly to `sys.stdout`, you shoul to `cmd2.Cmd.poutput`, `cmd2.Cmd.perror`, and `cmd2.Cmd.pfeedback`. These methods work with several of the built in [Settings](../features/settings.md) to allow the user to view or suppress feedback (i.e. progress or status output). They also properly handle ANSI colored output according to user -preference. Speaking of colored output, you can use any color library you want, or use the included -`cmd2.string_utils.stylize` function. These and other related topics are covered in -[Generating Output](../features/generating_output.md). +preference. `cmd2`'s dependency on `rich` makes it easy to add color and style to your output. See +the [Colored Output](../features/generating_output.md#colored-output) section for more details. +These and other related topics are covered in [Generating Output](../features/generating_output.md).