Skip to content

Rich help

By default --help prints your usage message verbatim, exactly as docopt does. The help text you wrote is what the user sees.

Opt into help_style="rich" and docopt2 renders an aligned, colored help screen instead. It documents where each value resolves from and is scoped to the command path the user typed, all from the same annotations docopt2 already reads.

from docopt2 import docopt

docopt(doc, help_style="rich")   # -h/--help now renders the rich screen

Value provenance

Rich help pulls the [env: ...], [config: ...] and [default: ...] annotations out of each option's description, and renders them as a dimmed resolution chain.

The chain is printed in the precedence order docopt2 actually resolves it. Given:

Serve a directory over HTTP.

Usage:
  serve [--port=<n>] [--host=<h>] [--log=<lvl>] <root>

Options:
  --port=<n>  Port to bind [default: 8080] [env: PORT] [config: server.port].
  --host=<h>  Interface to bind [default: 127.0.0.1] [env: HOST].
  --log=<lvl>  Log verbosity [default: info] [config: logging.level].

serve --help renders each option's human description clean, with its sources spelled out beside it:

Serve a directory over HTTP. Usage: serve [--port=<n>] [--host=<h>] [--log=<lvl>] <root> Options: --port=<n> Port to bind. [env: PORT, config: server.port, default: 8080] --host=<h> Interface to bind. [env: HOST, default: 127.0.0.1] --log=<lvl> Log verbosity. [config: logging.level, default: info]

The sources live in the usage text, so the help documents itself. Wire them imperatively instead, and they scatter across the code, where a help screen can only reach them through a second description you maintain by hand.

See Layered value resolution for how the chain resolves.

Scoped to the subcommand

Rich help also narrows to the subcommand. prog <sub> --help shows only the usage lines for <sub> and the options they use.

For a git-shaped CLI, git commit --help drops push and --force entirely:

Git. Usage: git commit [--message=<msg>] [--amend] Options: --message=<msg> Commit message to record. --amend Amend the last commit.

The scope is every positional token in the argv that is a command literal in the usage (here, commit). The usage narrows to the lines that carry all of them.

  • Position does not matter. --help commit scopes the same as commit --help.
  • A path that matches no single line, or no path at all, shows the whole usage.

Raw by default

help_style defaults to "raw", so nothing changes unless you opt in. The usage message prints exactly as written, preserving docopt's what-you-write-is-what-they-see contract.

"rich" adds the color above when the output is a terminal, and plain text when piped. Any other value raises ValueError.

Zero dependencies

The rich screen is rendered by docopt2 itself, reusing the same ANSI styling as the diagnostics - no rich, no config, no new dependency.

See also