Sphinx Integration¶
cliff supports integration with Sphinx by way of a Sphinx directives.
-
.. autoprogram-cliff::namespace¶ Automatically document an instance of
cliff.command.Command, including a description, usage summary, and overview of all options... autoprogram-cliff:: openstack.compute.v2 :command: server add fixed ip
One argument is required, corresponding to the namespace that the command(s) can be found in. This is generally defined in the entry_points section of either setup.cfg or setup.py. Refer to the example below for more information.
In addition, the following directive options can be supplied:
:command:
The name of the command, as it would appear if called from the command line without the executable name. This will be defined in setup.cfg or setup.py albeit with underscores. This is optional and fnmatch-style wildcarding is supported. Refer to the example below for more information.:application:
The top-level application name, which will be prefixed before all commands. This option overrides the global option autoprogram_cliff_application described below. In most cases the global configuration is enough, but this option is useful if your sphinx document handles multiple cliff applications.
See also
The
autoprogram_cliff_applicationconfiguration option.:ignored:
A comma-separated list of options to exclude from documentation for this option. This is useful for options that are of low value.
See also
The
autoprogram_cliff_ignoredconfiguration option.The following global configuration values are supported. These should be placed in conf.py:
autoprogram_cliff_application
The top-level application name, which will be prefixed before all commands. This is generally defined in the console_scripts attribute of the entry_points section of either setup.cfg or setup.py. Refer to the example below for more information.
For example:
autoprogram_cliff_application = 'my-sample-application'
Defaults to
''See also
The
:command:directive option.See also
The
:application:directive option.autoprogram_cliff_ignored
A global list of options to exclude from documentation. This can be used to prevent duplication of common options, such as those used for pagination, across all options.
For example:
autoprogram_cliff_ignored = ['--help', '--page', '--order']
Defaults to
['--help']See also
The
:ignored:directive option.
See also
- Module sphinxcontrib.autoprogram
- An equivalent library for use with plain-old argparse applications.
- Module sphinx-click
- An equivalent library for use with click applications.
Important
The autoprogram-cliff directive emits code-block
snippets marked up as shell code. This requires pygments >= 0.6.
Example¶
Take a sample setup.cfg file, which is based on the setup.cfg for the python-openstackclient project:
[entry_points]
console_scripts =
openstack = openstackclient.shell:main
openstack.compute.v2 =
host_list = openstackclient.compute.v2.host:ListHost
host_set = openstackclient.compute.v2.host:SetHost
host_show = openstackclient.compute.v2.host:ShowHost
This will register three commands - host list, host set and host
show - for a top-level executable called openstack. To document the first
of these, add the following:
.. autoprogram-cliff:: openstack.compute.v2
:command: host list
You could also register all of these at once like so:
.. autoprogram-cliff:: openstack.compute.v2
:command: host *
Finally, if these are the only commands available in that namespace, you can omit the :command: parameter entirely:
.. autoprogram-cliff:: openstack.compute.v2
In all cases, you should add the following to your conf.py to ensure all usage examples show the full command name:
autoprogram_cliff_application = 'openstack'
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.