Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/features/argument_processing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
21 changes: 18 additions & 3 deletions docs/features/generating_output.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:

Expand All @@ -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
Expand Down
3 changes: 3 additions & 0 deletions docs/features/table_creation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
6 changes: 3 additions & 3 deletions docs/migrating/next_steps.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Loading