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

cliff/sphinxext.py

@@ -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', '')

doc/source/user/sphinxext.rst

@@ -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`