Usage¶
sphinx-click enables automatic documentation 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 the parser object as its sole argument.
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.
Example¶
Take the below click application, which is defined in the example_app module:
import click
@click.group()
def greet():
"""A sample command group."""
pass
@greet.command()
@click.argument('user')
def hello(user):
"""Greet a user."""
click.echo('Hello %s' % user)
@greet.command()
def world(user):
"""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
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.