Automatic CLI reference in your docs pages (MkDocs, Markdown Exec)

[pawamoy]

Install Markdown Exec in your environment, list it in the plugins configuration of mkdocs.yml. In one of your Markdown pages, add this code block:

```python exec="1" idprefix=""
import cappa
from cappa.base import collect
from cappa.help import generate_arg_groups

from your_project.cli import YourMainCommand


def render_cli(command: cappa.Command, title: str, heading_level: int = 3) -> str:
    result = [f"{'#' * heading_level} **`{title}`**\n"]
    if command.help:
        result.append(f"> {command.help}\n")
    if command.description:
        result.append(f"{command.description}\n")

    for name, group in sorted(generate_arg_groups(command)):
        result.append(f"*{name.title()}*\n")
        for arg in group:
            if isinstance(arg, cappa.Subcommand):
                for option in arg.options.values():
                    result.append(
                        render_cli(option, option.real_name(), heading_level + 1)
                    )
                continue

            opts = [f"`{opt}`" for opt in arg.names()]
            if not opts:
                line = f"- `{arg.field_name}`"
            else:
                line = f"- {', '.join(opts)}"

            line += f" `{arg.value_name.upper()}`" if arg.num_args else ""
            line += f": {arg.help}"
            if arg.default is not cappa.Arg.default:
                default = str(arg.default)
                line += f" Default: `{default}`."
            result.append(line)
        result.append("")

    return "\n".join(result)


command = collect(YourMainCommand, help=False, completion=False)
print(render_cli(command, "your-cli-name"))
```

Thanks to @DanCardin for the original snippet.