Mkdocs rich argparse

An MkDocs plugin to generate documentation for a rich argparse parser. It renders commands, sub commands and sub-sub commands which can have rich help messages.

Installation

pip install mkdocs-rich-argparse

Usage

TL;DR: Set package to your installed CLI package's project name and add cli.md to your navigation.

1. Define your commands in your package's pyproject.toml using [project.scripts]:

   [project]
   name = "my-package"
   
   [project.scripts]
   myprogram = "my_package.cli:main"
   mysecondprogram = "my_package.cli:download"

2. Ensure your CLI package is installed alongside the plugin so its script metadata is available.

3. In mkdocs.yml, set package to the [project].name value from your pyproject.toml and add the generated page to your navigation:

   plugins:
       - mkdocs-rich-argparse:
           package: my-package
   
   nav:
       - CLI Reference: cli.md

Parsers are captured at parse_args() or parse_known_args(). Code before parsing still executes during the documentation build.

See the example/ directory for a minimal example and a custom styled example.

Configuration

package is required. All other plugin settings are optional and belong under mkdocs-rich-argparse in mkdocs.yml:

Setting	Default	Description
src_uri	cli.md	Generated page path relative to the docs directory. Update nav to match.
heading	CLI Reference	Top-level heading of the generated page.
order	[]	Script names to document first, in the specified order.
styles	See below	Rich styles for the generated help text.

For example, customize the page path and heading and put your main script first:

plugins:
  - mkdocs-rich-argparse:
      package: my-package
      src_uri: reference/commands.md
      heading: Commands
      order:
        - myprogram

nav:
  - Commands: reference/commands.md

Scripts listed in order appear first, in the specified order. All remaining scripts are sorted alphabetically. Unknown or duplicate script names cause a build error. If no order is specified, all scripts are sorted alphabetically.

Styles

The styles mapping accepts Rich style strings for args, groups, help, metavar, syntax, text, and default. The plugin sets help and text to green by default so they remain visible in dark mode. Other values keep the current RichHelpFormatter styles unless overridden.

plugins:
  - mkdocs-rich-argparse:
      package: my-package
      styles:
        args: bright_red
        groups: bright_green
        metavar: bright_magenta
        syntax: dark_orange
        help: bright_cyan
        text: bright_yellow
        default: bright_black

Colors in Continuous Integration

To preserve Rich colors in CI, set these environment variables (GitHub Actions example):

env:
    TTY_COMPATIBLE: '1'
    TTY_INTERACTIVE: '0'

Contributing

If you want to contribute to the development of mkdocs_rich_argparse, have a look at the contribution guidelines.