sphinxext: Add 'application' option to the autoprogram directive

In some cases, a single documentation build wants to handle multiple
cliff-based CLI. One possible example is openstack-manuals CLI ref.
In this case, the global setting 'autoprogram_cliff_application'
does not work. It is nice if we can specify an application name
per autoprogram-cliff directive.
This commit introduces a new option 'application' to
autoprogram-cliff directive to allow this.

Change-Id: Ie2d01920dc04f2a92031a641d809f7da8af8b395
This commit is contained in:
Akihiro Motoki 2017-06-01 02:46:38 +00:00
parent 807c910c4f
commit ccd2e048c6
2 changed files with 13 additions and 2 deletions

View File

@ -204,6 +204,7 @@ class AutoprogramCliffDirective(rst.Directive):
option_spec = {
'command': directives.unchanged,
'ignored': directives.unchanged,
'application': directives.unchanged,
}
def _load_command(self, manager, command_name):
@ -267,7 +268,8 @@ class AutoprogramCliffDirective(rst.Directive):
self.env = self.state.document.settings.env
command_pattern = self.options.get('command')
application_name = self.env.config.autoprogram_cliff_application
application_name = (self.options.get('application')
or self.env.config.autoprogram_cliff_application)
global_ignored = self.env.config.autoprogram_cliff_ignored
local_ignored = self.options.get('ignored', '')

View File

@ -29,6 +29,14 @@ cliff supports integration with Sphinx by way of a `Sphinx directives`__.
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.
.. seealso:: The ``autoprogram_cliff_application`` configuration option.
`:ignored:`
@ -44,7 +52,7 @@ cliff supports integration with Sphinx by way of a `Sphinx directives`__.
`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
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.
@ -57,6 +65,7 @@ cliff supports integration with Sphinx by way of a `Sphinx directives`__.
Defaults to ``''``
.. seealso:: The ``:command:`` directive option.
.. seealso:: The ``:application:`` directive option.
`autoprogram_cliff_ignored`