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

Install from Pypi:

pip install mkdocs-rich-argparse

Usage

In your mkdocs.yml configuration file, add the plugin and configure it with the module and factory to document:

plugins:
    - mkdocs-rich-argparse:
        module: my_module
        factory: my_factory_function

nav:
   - CLI Reference: cli.md

Where my_module is the Python module containing your argparse parser factory function, and my_factory_function is the specific function that returns an argparse parser object. It should be callable without arguments. You can optionally add path to specify the path to the module if it's not in the Python path.

When serving or building your MkDocs site, the plugin will generate a cli.md file containing the documentation for the specified argparse parser.

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

Colors in Continuous Integration

If you are building the mkdocs site in a Continuous Integration (CI) environment, the colors might not render correctly. To fix this add TTY_COMPATIBLE=1 and TTY_INTERACTIVE=0 environment variables to your CI configuration.

For example in GitHub Actions add the following to your workflow file:

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.