{"id":5062,"library":"sphinx-click","title":"Sphinx Click","description":"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.","status":"active","version":"6.2.0","language":"en","source_language":"en","source_url":"https://github.com/click-contrib/sphinx-click","tags":["sphinx","click","documentation","cli","extension","autodocumentation"],"install":[{"cmd":"pip install sphinx-click","lang":"bash","label":"Install sphinx-click"}],"dependencies":[{"reason":"Core dependency for documenting Click applications. Version 8.0.0 or higher is required since sphinx-click 6.0.0.","package":"click","optional":false},{"reason":"The documentation generator framework. Version 4.0.0 or higher is required since sphinx-click 6.0.0.","package":"Sphinx","optional":false}],"imports":[{"note":"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'.","wrong":"extensions = ['sphinx_click.ext']","symbol":"sphinx_click","correct":"extensions = ['sphinx_click']"}],"quickstart":{"code":"# docs/conf.py\nimport os\nimport sys\nsys.path.insert(0, os.path.abspath('.'))\n\nproject = 'My Click App Docs'\ncopyright = '2026, My Team'\nextensions = ['sphinx_click']\nhtml_theme = 'alabaster'\n\n# hello_world.py\nimport click\n\n@click.group()\ndef cli():\n    \"\"\"A sample command group.\"\"\"\n    pass\n\n@cli.command()\n@click.argument('name', envvar='USER', default='World')\ndef hello(name):\n    \"\"\"Greet a user or the world.\n\n    :param name: The name to greet. Defaults to the USER environment variable if set.\n    \"\"\"\n    click.echo(f'Hello {name}!')\n\n@cli.command()\ndef goodbye():\n    \"\"\"Say goodbye.\n\n    \"\"\"\n    click.echo('Goodbye!')\n\n# docs/index.rst\n.. toctree::\n   :maxdepth: 2\n   :caption: Contents:\n\n   cli\n\n.. click:: hello_world:cli\n   :prog: myapp\n   :nested: full\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Click dependency to version 8.0.0 or newer (e.g., `pip install 'click>=8.0.0'`).","message":"sphinx-click 6.0.0 dropped support for Click 7.x. Your Click application must use Click 8.0.0 or higher.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Upgrade your Sphinx dependency to version 4.0.0 or newer (e.g., `pip install 'Sphinx>=4.0.0'`).","message":"sphinx-click 6.0.0 dropped support for Sphinx versions older than 4.0.0. Ensure your Sphinx installation meets this minimum requirement.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Ensure your project runs on Python 3.10 or a newer supported version.","message":"As of sphinx-click 6.1.0, Python 3.8 and 3.9 are no longer supported.","severity":"breaking","affected_versions":">=6.1.0"},{"fix":"Use the `:nested:` option instead, with values like `full`, `short`, or `none`.","message":"The `:show-nested:` option for the `.. click::` directive is deprecated.","severity":"deprecated","affected_versions":">=6.1.0"},{"fix":"Use the `:ref:` role instead, with labels generated by sphinx-click in the format `{command_name}-{param_name}-{envvar}`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}