sphinx-click

library6.2.0pypypi✓ verified 28d ago

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.

web-framework

pip install sphinx-click

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · SPHINX-CLICK

sphinx-click

web-frameworkpythonv6.2.0

Install

5.5s avg

Import

—

Disk

95MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v6.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 93.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 5.5s · import 0.000s · 94MB

95MB installed

● package 95MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

sphinx_click

✓ extensions = ['sphinx_click']

✗ extensions = ['sphinx_click.ext']

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

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

Debug

Known issues

breakingsphinx-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'`).

affects: >=6.0.0

breakingsphinx-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'`).

affects: >=6.0.0

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

affects: >=6.1.0

deprecatedThe `:show-nested:` option for the `.. click::` directive is deprecated.

fix

Use the `:nested:` option instead, with values like `full`, `short`, or `none`.

affects: >=6.1.0

gotchaCross-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}`.

affects: All

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

affects: All

Upgrade

Version history

6.2.0latest on PyPI · released Dec 4, 2025

Audit

Dependencies

clickrequiredCore dependency for documenting Click applications. Version 8.0.0 or higher is required since sphinx-click 6.0.0.

SphinxrequiredThe documentation generator framework. Version 4.0.0 or higher is required since sphinx-click 6.0.0.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/click-contrib/sphinx-click ↗

packagehttps://pypi.org/project/sphinx-click/ ↗

docshttps://sphinx-click.readthedocs.io/en/latest ↗