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

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

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