cliff supports integration with Sphinx by way of a Sphinx directives.
Before using the autoprogram-cliff
directive you must add
‘cliff.sphinxext’ extension module to a list of extensions in conf.py:
extensions = ['cliff.sphinxext']
.. 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:
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_application
configuration option.
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_ignored
configuration option.
The following global configuration values are supported. These should be placed in conf.py:
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.
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
Important
The autoprogram-cliff
directive emits code-block
snippets marked up as shell code. This requires pygments >= 0.6.
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.