Usage¶
To enable the plugin, add the extension to the list of extensions in your Sphinx conf.py file:
extensions = ['sphinx_click.ext']
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 :show-nested:
The directive takes the import name of a click object as its sole argument. This should be a subclass of
click.core.BaseCommand
, such asclick.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 beboo
. If this is not given, the module name is used.
The following options are optional:
:show-nested:
Enable full documentation for sub-commands.
:commands:
Document only listed commands.
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
If you wish to include full documentation for the subcommand, hello
, in the
output, add the show-nested
flag.
.. click:: hello_world:greet
:prog: hello-world
:show-nested:
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
:show-nested:
assuming the group or command in git.git
is named cli
.
Refer to issue #2 for more information.