CLI Documentation

If your Python package includes a command-line interface built with Click, Great Docs can generate reference pages for it automatically. Each command and subcommand gets its own page showing the full --help output in a terminal-style format. This means your CLI documentation stays perfectly in sync with your code, because the help text is captured directly from Click at build time.

This page covers how to enable CLI documentation, how Great Docs discovers your commands, what the generated pages look like, and how to write CLI help text that produces clear, useful reference pages.

Enabling CLI Documentation

Add the following to your great-docs.yml:

great-docs.yml
cli:
  enabled: true

With this single setting, Great Docs handles the rest: it finds your Click commands, captures their help output, and generates reference pages during every build. No additional configuration is needed for standard project layouts.

How It Works

When CLI documentation is enabled, Great Docs runs a pipeline that mirrors how it handles API documentation: discover, extract, generate, and integrate. Here’s what happens during each build:

  1. Finds your CLI: looks for Click commands in common locations
  2. Discovers entry point: reads [project.scripts] from pyproject.toml
  3. Extracts help text: captures --help output for each command and subcommand
  4. Generates pages: creates .qmd files in reference/cli/
  5. Updates navigation: adds a CLI section to the sidebar

The pipeline runs as part of great-docs build, so CLI pages are always regenerated from the current state of your code. You never need to update them manually.

Auto-Discovery

Most Click-based packages follow a handful of common patterns for where the CLI entry point lives. Great Docs checks these locations automatically, so you rarely need to tell it where to look:

  1. your_package.cli: the most common location
  2. your_package.__main__: for python -m your_package support
  3. your_package.main: alternative location
  4. entry point module from [project.scripts]

Great Docs tries each location in order and uses the first one that contains a Click command.

Entry Point Detection

If you have a [project.scripts] section:

pyproject.toml
[project.scripts]
my-cli = "my_package.cli:main"

Great Docs uses my-cli as the command name in documentation.

Explicit Configuration

If your CLI lives in a non-standard location, or if auto-discovery picks up the wrong command object, you can specify the module and command name explicitly in great-docs.yml:

great-docs.yml
cli:
  enabled: true
  module: my_package.commands   # Module containing Click commands
  name: app                      # Name of the Click command object

The module value should be the dotted import path to the Python module containing your Click group or command. The name value is the variable name of the Click command object within that module. With explicit configuration, Great Docs skips auto-discovery entirely and goes straight to the specified location.

Generated Output

Once Great Docs discovers your CLI, it generates a set of reference pages that integrate into the existing site navigation. Here’s what to expect.

Page Format

Each CLI page displays the --help output in a terminal-style format:

Usage: my-cli build [OPTIONS] PATH

  Build the project at PATH.

  This command compiles all source files and generates output
  in the specified directory.

Options:
  --output DIR    Output directory (default: ./dist)
  --verbose       Enable verbose output
  --help          Show this message and exit.

The styling mimics a terminal with:

  • Dark background
  • Monospace font
  • Proper spacing for readability

The result is a set of browsable reference pages that feel familiar to anyone who has used --help in a terminal, but with the convenience of being searchable and navigable within your documentation site.

Writing Good CLI Help

The quality of your CLI documentation depends entirely on the help text you write in your Click decorators and docstrings. Great Docs displays this text as-is, so investing in clear, descriptive help strings pays off directly in the generated pages.

Use Descriptive Help Text

Every Click command should have a docstring that explains what it does. The first line becomes the short description shown in --help listings, and the full text appears on the command’s dedicated reference page:

cli.py
@click.command()
@click.argument("path")
@click.option("--output", "-o", help="Output directory for generated files")
@click.option("--verbose", "-v", is_flag=True, help="Enable verbose logging")
def build(path, output, verbose):
    """
    Build the project at PATH.

    This command compiles all source files and generates output
    in the specified directory. Use --verbose to see detailed
    progress information.
    """
    ...

Document All Options

Every @click.option() should include a help= string. Options without help text appear in the reference page but give readers no indication of what they do:

cli.py
@click.option(
    "--format",
    type=click.Choice(["json", "yaml", "toml"]),
    default="json",
    help="Output format (default: json)"
)

Use Click Groups for Subcommands

If your CLI has multiple commands, use a @click.group() to organize them. Great Docs generates a separate page for each subcommand and links them together in the sidebar:

cli.py
@click.group()
def cli():
    """My CLI application for managing projects."""
    pass

@cli.command()
def init():
    """Initialize a new project."""
    ...

@cli.command()
def build():
    """Build the project."""
    ...

Well-structured Click groups produce the clearest documentation. Each subcommand becomes its own page, and the group’s docstring serves as the overview for the CLI section.

Example: Great Docs CLI

Great Docs uses this feature to document its own CLI. The generated pages show how the main command and its subcommands appear in the reference section:

Main command (great-docs):

Usage: great-docs [OPTIONS] COMMAND [ARGS]...

  Great Docs - Beautiful documentation for Python packages.

  Generate professional documentation sites with auto-discovered API
  references, CLI documentation, and smart navigation.

Commands:
  init              Initialize great-docs in your project
  build             Build documentation site
  preview           Build and preview locally
  scan              Scan package exports
  setup-github-pages  Create GitHub Pages workflow
  uninstall         Remove great-docs from project

Subcommand (great-docs build):

Usage: great-docs build [OPTIONS]

  Build your documentation site.

  Generates API reference pages and runs quarto render
  to build the HTML site.

Options:
  --no-refresh  Skip API discovery refresh (faster rebuild)
  --watch       Watch for changes and rebuild
  --help        Show this message and exit.

You can see these pages live in the Great Docs reference section. They are regenerated on every build from the actual Click commands, so they always reflect the current set of options and subcommands.

Styling

CLI reference pages use a distinct visual treatment that sets them apart from API reference pages:

  • disables the sidebar filter (CLIs are usually small)
  • removes breadcrumb navigation
  • uses a wider content area on large screens
  • maintains responsive design on mobile

These styling choices keep CLI pages clean and focused, matching the terminal-centric nature of the content.

Troubleshooting

If CLI documentation isn’t working as expected, here are the most common issues and how to resolve them.

CLI Not Detected

If your CLI isn’t found:

  1. verify Click is installed
  2. check the module path is correct
  3. ensure the Click command is importable
  4. use explicit configuration:
great-docs.yml
cli:
  enabled: true
  module: your_package.cli
  name: cli   # The Click command object name

Help Text Missing

If commands show minimal help:

  1. add docstrings to your Click functions
  2. add help= to all options
  3. use @click.argument() with proper names

Next Steps

CLI documentation works best when your Click commands already have good help text and docstrings. Great Docs takes what you’ve written and turns it into browsable, searchable reference pages that stay in sync with your code.