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 structured page showing the usage signature, description, typed options, and examples, all using the same layout as API reference pages. This means your CLI documentation stays perfectly in sync with your code, because everything is extracted 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 metadata: introspects each command for its description, options, arguments, subcommands, and examples
  4. Generates structured pages: creates .qmd files in reference/cli/ with the same layout as API reference pages
  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 uses the same structured layout as API reference pages, making the site feel cohesive. A generated page contains these sections in order:

  1. Title with a colored label badge (cli or cli-group)
  2. Subject: the first paragraph of your docstring (the short description)
  3. Usage signature: a bash code block showing the invocation pattern
  4. Extended description: remaining paragraphs from your docstring, formatted as prose
  5. Collapsible --help output: the full raw --help text, tucked inside a disclosure widget
  6. Arguments: if the command takes positional arguments
  7. Options: a definition list with name, type, default, and help text
  8. Subcommands: for groups, each subcommand links to its own page
  9. Examples: if your docstring includes an Examples: section

This structured layout gives readers quick access to what they need (usage, options, examples) while preserving the full --help output for those who want the raw reference.

Text enhancements

Within the description and option help text, Great Docs automatically applies two enhancements:

  • Single-quoted text → code: 'great-docs build' in your docstring renders as great-docs build in inline code
  • Option names → code: references to options like --watch or --from-repo are rendered as inline code automatically

These enhancements are applied automatically during page generation. You don’t need to use backticks or any special markup in your Click docstrings or help= strings.

Writing Good CLI Help

The quality of your CLI documentation depends on the help text you write in your Click decorators and docstrings. Great Docs parses your docstrings into structured sections, so following a few conventions produces the best results.

Use Descriptive Help Text

Every Click command should have a docstring that explains what it does. The first paragraph becomes the subject (displayed prominently at the top of the page), and remaining paragraphs form the extended description:

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.
    """
    ...

The first paragraph is especially important because it also appears as the short description in the parent group’s Commands list and in search results.

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. Use single quotes around file names or values to have them rendered as inline code:

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

In the generated page, 'pyproject.toml' in the second option’s help text becomes inline code automatically, so the rendered description reads “Path to config file (default: pyproject.toml)”.

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.

Include Examples

If your docstring contains a paragraph starting with Examples:, Great Docs extracts it into a dedicated Examples section rendered as a bash code block. Use Click’s \b marker to prevent paragraph rewrapping:

cli.py
@click.command()
def deploy():
    """Deploy the built site.

    Uploads the contents of _site/ to your configured host.

    \b
    Examples:
      my-cli deploy                  # Deploy to production
      my-cli deploy --dry-run        # Preview what would happen
      my-cli deploy --target staging # Deploy to staging
    """
    ...

Without the \b marker, Click joins continuation lines into a single paragraph, which would collapse the example lines together. Always place \b on its own line before Examples: to preserve the formatting.

Example: Great Docs CLI

Great Docs uses this feature to document its own CLI. Here’s what the generated page for great-docs build looks like (simplified):

Subject and usage:

Build your documentation site.

great-docs build [OPTIONS]

Extended description (formatted as prose):

Requires great-docs.yml to exist (run great-docs init first). This is the only command you need day-to-day and in CI.

Collapsible --help output:

The full raw terminal output is available inside a disclosure widget labeled “Full –help output”. Readers can expand it when they want the complete reference, but it doesn’t dominate the page.

Options (structured definition list):

Option Type Description
--watch flag Watch for changes and rebuild automatically
--no-refresh flag Skip re-discovering package exports
--versions TEXT Build only specific versions (comma-separated)
--from-repo TEXT Clone a remote Git repository and build its docs

Examples (bash code block):

great-docs build                      # Full build with API refresh
great-docs build --no-refresh         # Fast rebuild (skip API discovery)
great-docs build --watch              # Rebuild on file changes

The main group page (great-docs) additionally includes a Commands section that links to each subcommand’s dedicated page. You can see these pages live in the Great Docs reference section. All of these sections are generated from the same Click decorators and docstrings shown earlier in this guide.

Styling

CLI reference pages share the same visual system as API reference pages:

  • Colored label badges: cli (blue) and cli-group (teal) distinguish commands from groups
  • Structured definition lists: options are displayed with the same parameter styling used for function signatures in API docs
  • Consistent layout: subject, signature, description, and parameters mirror the API page structure
  • Responsive design: pages adapt to mobile and desktop viewports
  • Collapsible details: the raw --help output is available but doesn’t clutter the page

This shared design language means readers moving between API docs and CLI docs see the same patterns: a short subject at the top, a signature block, extended prose, and a structured parameter list.

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

If auto-discovery finds a Click command but it’s the wrong one, explicit configuration lets you point to the correct object directly.

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

The generated page will still show the command’s usage signature and options, but the subject and extended description sections will be empty without a docstring.

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.