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.

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.

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

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.