sphinx-click
Contents
1 Installation 3 2 Usage 5 2.1 Example . . . 6 2.2 Modifying sys.path. . . 7 3 Contribution 9 3.1 Support . . . 9 3.2 Reporting Issues . . . 9 3.3 Submitting Patches . . . 9 3.4 Testing . . . 10 4 Changes 11 4.1 2.5.0 . . . 11 4.2 2.4.0 . . . 11 4.3 2.3.2 . . . 11 4.4 2.3.1 . . . 12 4.5 2.3.0 . . . 12 4.6 2.2.0 . . . 12 4.7 2.1.0 . . . 12 4.8 2.0.1 . . . 12 4.9 2.0.0 . . . 12 4.10 1.4.1 . . . 13 4.11 1.4.0 . . . 13 4.12 1.3.0 . . . 13 4.13 1.2.0 . . . 13 4.14 1.1.0 . . . 14 4.15 1.0.4 . . . 14 4.16 1.0.3 . . . 14 4.17 1.0.2 . . . 14 4.18 1.0.1 . . . 14 4.19 1.0.0 . . . 14 Index 15 isphinx-click
sphinx-clickis aSphinxplugin that allows you to automatically extract documentation from aclick-based appli-cation and include it in your docs.
sphinx-click
CHAPTER
1
Installation
Install the plugin using pip:
$ pip install sphinx-click
Alternatively, install from source by cloning this repo then running setup.py:
$ python setup.py install
Important: Both the package you’re referencing and any dependencies must be installed.
sphinx-click
CHAPTER
2
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 forclick-basedapplications by way of aSphinx directive.
.. click:: module:parser
Automatically extract documentation from aclick-basedapplication 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 ofclick. 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.
sphinx-click
: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 theSphinx standard domain.
2.1 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 documen-tation 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
sphinx-click
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 theSphinx issuefor more information.
2.2 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 toissue #2for more information.
sphinx-click
CHAPTER
3
Contribution
We welcome all contributions to sphinx-click.
3.1 Support
Open and issue in theissue trackerfor all support requests.StackOverflowis also worth considering.
3.2 Reporting Issues
Report all issues in theissue tracker. When doing so, please include version information for: • Python
• click • sphinx-click
3.3 Submitting Patches
All patches should be submitted as pull requests on theGitHub project. • Include tests if fixing a bug
• Clearly explain what you’re trying to accomplish • FollowPEP 8. You can use the pep8 tox target for this
sphinx-click
3.4 Testing
sphinx-clickuses tox and unittest for testing. To run all tests, run:
$ tox
We support a number of Python versions. To list available environments, run:
$ tox --list
To run one of these environments, such as py27 which runs tests under Python 2.7, run:
$ tox -e py27
CHAPTER
4
Changes
• add whitespace to option choice separator to allow wrapping
4.1 2.5.0
• Make show-nested more granualar • Add support for epilogs
• Support ‘metavar’
• Prettier formatting of detailed opt information • Allow extension to be used as simply ‘sphinx_click’ • trivial: Separate imports
4.2 2.4.0
• tests: Add docstrings
• Use ‘nested_parse_with_titles’ • Switch to black
4.3 2.3.2
• requirements: Add support for Sphinx 3.x
sphinx-click
4.4 2.3.1
• Make sphinx version in sync with the conda package • Fixed sphinx version in requirements.txt (#52)
4.5 2.3.0
• improvement: remove the excessive comma in list.append() function call • improvement: describe when and why show_default can be a string • fix: when ‘show_default’ is a string use it as the default description • trivial: Unify ‘hidden’ checks
• Don’t show hidden commands in toctree • trivial: Black fixups
• Drop support for Python 3.4
4.6 2.2.0
• Add pre-commit support • Misc formatting fixes
• Add instruction to usage docs to enable extension (#45) • Change display format to pull options out of in line help text • Add click.Choice options to help text
• Update sphinx supported version
4.7 2.1.0
• Support and test Sphinx 2 and Python 3.7
4.8 2.0.1
• Do not show hidden subcommands as valid command options
4.9 2.0.0
• Misc formatting fixes
• Remove use of ‘build_sphinx’ • README: Add docs badge
sphinx-click
• Ignore hidden commands
• Start testing Click 7.x, drop support for 5.x • Fix compatibility with Click 7.0
4.10 1.4.1
• Use unique anchors for envvars • Log output
• README: Add Travis badge
4.11 1.4.0
• Use unique identifiers for envvars • travis: Update PyPI password
• Add tests for disabled line rewrapping • Updated implementation of philipstarkey’s fix • Revert “tox: Start testing Python 3.7”
• tox: Start testing Python 3.7
• doc: Document how cross-referencing works • travis: Use travis to publish packages • tox: Add pypy testing
• travis: Reformat file using travis linter
4.12 1.3.0
• docs: Expand on what a “click object” is • Check type of object to document • trivial: Fix formatting issues • tox: Apply style changes
4.13 1.2.0
• tests: Add tests for MultiCommand • Support lazyload commands
sphinx-click
4.14 1.1.0
• Use short_help if help is absent • trivial: style target for Tox
• Improved code style using Yapf and ISort • travis: Add basic configuration
• trivial: Fix broken pep8 target
• Add :commands: option for click directive
4.15 1.0.4
• Provide more context for import errors
4.16 1.0.3
• Fix Sphinx 1.7 compatibility
• Fix unicode from breaking module import • Add various _format_XXX functions
4.17 1.0.2
• sorts the commands and subcommands • tox: Add ‘release’ target
4.18 1.0.1
• docs: Add example for modifying ‘sys.path’ • Handle commands without a docstring • README: Update usage example
4.19 1.0.0
• Initial release • Basic project setup • Initial commit See also:
Module click This extension assumes you are using click to create your command line application. Module sphinxcontrib.autoprogram An equivalent library for use with argparse.
Index
C
click(directive),5
P
Python Enhancement Proposals PEP 8,9
