Usage

To enable the plugin, add the extension to the list of extensions in your Sphinx conf.py file:

extensions = ['sphinx_click']

Once enabled, sphinx-click enables automatic documentation for click-based applications by way of a Sphinx directive.

.. click:: module:parser

Automatically extract documentation from a click-based application and include it in your docs.

.. click:: module:parser
   :prog: hello-world
   :nested: full

The directive takes the import name of a click object as its sole argument. This should be a subclass of click.core.BaseCommand, such as click.Command, click.Group, click.MultiCommand, etc.

In addition, the following options are required:

:prog:

The name of your tool (or how it should appear in your documentation). For example, if you run your script as ./boo --opts args then :prog: will be boo. If this is not given, the module name is used.

The following options are optional:

:nested:

Whether subcommands should also be shown. One of:

full

List sub-commands with full documentation.

short

List sub-commands with short documentation.

none

Do not list sub-commands.

Defaults to short unless show-nested (deprecated) is set.

:commands:

Document only listed commands.

:show-nested:

This option is deprecated; use nested instead.

The generated documentation includes anchors for the generated commands, their options and their environment variables using the Sphinx standard domain.

Cross-referencing

As discussed above, the documentation generated by sphinx-click includes anchors for the generated commands, their options and their environment variables using the Sphinx standard domain. Specifically, it uses the program, option, and envvar directives.

Options (e.g. --param)

The option directive can be cross-referenced using the :option: role.

Environment variables

The envvar directive can be cross-references using the :ref: role. sphinx-click generates labels in the format {command_name}-{param_name}-{envvar}. It is not currently possible to use the :envvar: role because the default labels generated by Sphinx are not namespaced and will generate conflicts if the same environment variable is used in multiple commands. See issue #26 for more information.

Programs

Sphinx currently does not allow you to cross-reference programs. See Sphinx issue #880 for more information.

Mocking

sphinx-click allows for modules to be mocked out using the same method used by sphinx.ext.autodoc. Modules to mock while the documentation is being built can be specified using the sphinx_click_mock_imports config value, if specified. Otherwise the value of autodoc_mock_imports is used, following the behavior of sphinx.ext.autosummary. The value of this config option should be a list of module names; see sphinx.ext.autodoc for more information.

Events

sphinx-click provides the following additional events:

sphinx-click-process-description(app, ctx, lines)

sphinx-click-process-usage(app, ctx, lines)

sphinx-click-process-options(app, ctx, lines)

sphinx-click-process-arguments(app, ctx, lines)

sphinx-click-process-envvars(app, ctx, lines)

sphinx-click-process-epilog(app, ctx, lines)

Parameters:

• app – the Sphinx application object

• ctx – the click.Context object used to generate the description

• lines – the lines of the documentation, see below

Events are emitted when sphinx-click has read and processed part of a command’s documentation. lines is a list of strings – the lines of the documentation that was processed – that the event handler can modify in place to change what Sphinx puts into the output.

def process_description(app, ctx, lines):
    """Append some text to the "example" command description."""
    if ctx.command.name == "example":
        lines.extend(["Hello, World!", ""])

def setup(app):
    app.connect("sphinx-click-process-description", process_description)

Example

Take the below click application, which is defined in the hello_world module:

import click

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

@greet.command()
@click.argument('user', envvar='USER')
def hello(user):
    """Greet a user."""
    click.echo('Hello %s' % user)

@greet.command()
def world():
    """Greet the world."""
    click.echo('Hello world!')

To document this, use the following:

.. click:: hello_world:greet
  :prog: hello-world

By default, the subcommand, hello, is listed but no documentation provided. If you wish to include full documentation for the subcommand in the output, configure the nested flag to full.

.. click:: hello_world:greet
  :prog: hello-world
  :nested: full

Note

The nested flag replaces the deprecated show-nested flag.

Conversely, if you do not wish to list these subcommands or wish to handle them separately, configure the nested flag to none.

.. click:: hello_world:greet
  :prog: hello-world
  :nested: none

You can also document only selected commands by using :commands: option.

.. click:: hello_world:greet
  :prog: hello-world
  :commands: hello

You can cross-reference the commands, option and environment variables using the roles provided by the Sphinx standard domain. See Cross-referencing for more information.

.. click:: hello_world:greet
   :prog: hello-world

The :program:`hello` command accepts a :option:`user` argument. If this is
not provided, the :envvar:`USER` environment variable will be used.

Note

Cross-referencing using the :program: directive is not currently supported by Sphinx. Refer to the Sphinx issue for more information.

Documenting CommandCollection

When building more complex CLI, one might need to bring together multiple groups of commands and make them accessible using a single client with CommandCollection. sphinx-click renders collection of commands with multiple sections, one for each group listed in the command sources. The group names are used as section titles and the help string from the description are used as section description. Thus, a client defined using a CommandCollection as cli can be rendered using sphinx-click and the following directive:

.. click:: cli:cli
   :prog: cli
   :nested: full

This will render the subcommands of each group in different sections, one for each group in sources. An example is provided in Documenting command collections.

Modifying sys.path

If the application or script you wish to document is not installed (i.e. you have not installed it with pip or run python setup.py), then you may need to modify sys.path. For example, given the following application:

git
  |- git
  |    |- __init__.py
  |    \- git.py
  \- docs
      |- git.rst
      |- index.rst
       \- conf.py

then it would be necessary to add the following to git/docs/conf.py:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Once done, you could include the following in git/docs/git.rst to document the application:

.. click:: git.git:cli
   :prog: git
   :nested: full

assuming the group or command in git.git is named cli.

Refer to issue #2 for more information.