Sphinx Click

6.2.0 · active · verified Sun Apr 12

sphinx-click is a Sphinx extension that automatically extracts documentation from Click-based command-line applications and integrates it into Sphinx documentation. It is currently at version 6.2.0 and receives regular updates, often with several releases per year.

Warnings

breaking sphinx-click 6.0.0 dropped support for Click 7.x. Your Click application must use Click 8.0.0 or higher.
Fix: Upgrade your Click dependency to version 8.0.0 or newer (e.g., `pip install 'click>=8.0.0'`).
breaking sphinx-click 6.0.0 dropped support for Sphinx versions older than 4.0.0. Ensure your Sphinx installation meets this minimum requirement.
Fix: Upgrade your Sphinx dependency to version 4.0.0 or newer (e.g., `pip install 'Sphinx>=4.0.0'`).
breaking As of sphinx-click 6.1.0, Python 3.8 and 3.9 are no longer supported.
Fix: Ensure your project runs on Python 3.10 or a newer supported version.
deprecated The `:show-nested:` option for the `.. click::` directive is deprecated.
Fix: Use the `:nested:` option instead, with values like `full`, `short`, or `none`.
gotcha Cross-referencing environment variables using the standard `:envvar:` role in Sphinx can cause conflicts if the same environment variable is used across multiple commands, due to Sphinx's non-namespaced default labels.
Fix: Use the `:ref:` role instead, with labels generated by sphinx-click in the format `{command_name}-{param_name}-{envvar}`.
gotcha Click docstrings often use the `\b` character for formatting. Sphinx-click might not render these characters correctly in HTML output, leading to broken formatting for lists or paragraphs intended for specific Click help screens.
Fix: Consider rephrasing docstrings or using reStructuredText formatting directly if `\b` causes undesirable output. This is a known limitation when translating Click's specific docstring formatting to Sphinx.

Install

pip install sphinx-click Install sphinx-click

Imports

sphinx_click
```
extensions = ['sphinx_click']
```
The correct extension name to add to `conf.py` is 'sphinx_click'. Older examples or certain contexts might show 'sphinx_click.ext', but the current official documentation uses 'sphinx_click'.

Quickstart

To quickly document a Click application, first set up a Sphinx project (e.g., using `sphinx-quickstart`). Create your Click application (e.g., `hello_world.py`). In your `conf.py`, add `'sphinx_click'` to the `extensions` list and ensure your application's path is included in `sys.path`. Then, in an RST file (e.g., `cli.rst`), use the `.. click::` directive, pointing to your Click command or group. The `:prog:` option specifies the command name to display, and `:nested: full` will document subcommands. Ensure the Click application and its dependencies are available in the build environment.

# docs/conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('.'))

project = 'My Click App Docs'
copyright = '2026, My Team'
extensions = ['sphinx_click']
html_theme = 'alabaster'

# hello_world.py
import click

@click.group()
def cli():
    """A sample command group."""
    pass

@cli.command()
@click.argument('name', envvar='USER', default='World')
def hello(name):
    """Greet a user or the world.

    :param name: The name to greet. Defaults to the USER environment variable if set.
    """
    click.echo(f'Hello {name}!')

@cli.command()
def goodbye():
    """Say goodbye.

    """
    click.echo('Goodbye!')

# docs/index.rst
.. toctree::
   :maxdepth: 2
   :caption: Contents:

   cli

.. click:: hello_world:cli
   :prog: myapp
   :nested: full

view raw JSON →