Add CLI auto generated documentation using Cliff

This patch adds the Cliff Sphinx Extension support for auto documenting
the `validation` Command Line Interface. It also standardizes the
`metavar` description for all the --group, --category and --product
arguments by using <group_id>, <category_id> and <product_id>.

Moreover, it removes usage example(s) in the arguments helpers which are often
duplicated with the `metavar`.

Change-Id: I3009337e8afadd705bbee5b89d9022c78093cdc8
Signed-off-by: Gael Chamoulaud (Strider) <gchamoul@redhat.com>

doc/requirements.txt

@@ -5,3 +5,4 @@ doc8>=0.8.0 # Apache-2.0
 sphinxcontrib-apidoc>=0.2.0  # BSD
 sphinxcontrib-svg2pdfconverter>=1.1.1  # BSD License
 reno>=3.1.0 # Apache-2.0
+cliff>=3.2.0 # Apache-2.0

doc/source/cli.rst

@@ -0,0 +1,22 @@
+.. _cli:
+
+==================================================
+Validations Framework Command Line Interface (CLI)
+==================================================
+
+The following documentation is generated using the `the cliff Sphinx extension
+<sphinxext>`.
+
+Output
+------
+
+Global Options
+~~~~~~~~~~~~~~
+
+.. autoprogram-cliff:: validations_libs.cli.app.ValidationCliApp
+   :application: validation
+
+Command Options
+~~~~~~~~~~~~~~~
+
+.. autoprogram-cliff:: validation.cli

doc/source/conf.py

@@ -27,6 +27,7 @@ sys.path.insert(0, os.path.join(os.path.abspath('.'), '_exts'))
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    'cliff.sphinxext',
     'sphinxcontrib.apidoc',
     'sphinxcontrib.rsvgconverter',
     'sphinx.ext.viewcode',
@@ -40,6 +41,7 @@ apidoc_output_dir = 'reference/api'
 apidoc_excluded_paths = []
 apidoc_separate_modules = True
 
+autoprogram_cliff_application = 'validation'
 
 # openstackdocstheme options
 openstackdocs_repo_name = 'openstack/validations-libs'

doc/source/index.rst

@@ -16,6 +16,7 @@ Contents
    readme
    contributing
    testing
+   cli
    reference/index
 
 Indices and tables

validations_libs/cli/history.py

@@ -30,7 +30,7 @@ class ListHistory(BaseLister):
         parser = super(ListHistory, self).get_parser(parser)
 
         parser.add_argument('--validation',
-                            metavar="<validation>",
+                            metavar="<validation_id>",
                             type=str,
                             help='Display execution history for a validation')
         parser.add_argument('--limit',
@@ -71,7 +71,7 @@ class ListHistory(BaseLister):
 
 
 class GetHistory(BaseCommand):
-    """Display details about a Validation execution"""
+    """Display details about a specific Validation execution"""
 
     def get_parser(self, parser):
         parser = super(GetHistory, self).get_parser(parser)

validations_libs/cli/lister.py

@@ -22,20 +22,18 @@ from validations_libs.cli.parseractions import CommaListAction
 
 
 class ValidationList(Lister):
-    """Validation List client implementation class"""
+    """List the Validations Catalog"""
 
     def get_parser(self, parser):
         """Argument parser for validation run"""
         parser = super(ValidationList, self).get_parser(parser)
         parser.add_argument('--group', '-g',
-                            metavar='<group>[,<group>,...]',
+                            metavar='<group_id>[,<group_id>,...]',
                             action=CommaListAction,
                             default=[],
                             help=("List specific group of validations, "
                                   "if more than one group is required "
-                                  "separate the group names with commas: "
+                                  "separate the group names with commas."))
-                                  "--group pre-upgrade,prep | "
-                                  "--group openshift-on-openstack"))
         parser.add_argument('--category',
                             metavar='<category_id>[,<category_id>,...]',
                             action=CommaListAction,

validations_libs/cli/run.py

@@ -25,17 +25,20 @@ from validations_libs.cli.parseractions import CommaListAction, KeyValueAction
 
 
 class Run(BaseCommand):
-    """Validation Run client implementation class"""
+    """Run Validations by name(s), group(s), category(ies) or by product(s)"""
 
     def get_parser(self, parser):
         """Argument parser for validation run"""
         parser = super(Run, self).get_parser(parser)
         parser.add_argument(
-            '--limit', action='store', required=False, help=(
+            '--limit',
+            action='store',
+            metavar="<host1>[,<host2>,<host3>,...]",
+            required=False,
+            help=(
                 "A string that identifies a single node or comma-separated "
                 "list of nodes to be upgraded in parallel in this upgrade "
-                " run invocation. For example: --limit \"compute-0,"
+                "run invocation."))
-                "compute-1,compute-5\"."))
 
         parser.add_argument(
             '--ssh-user',
@@ -80,15 +83,15 @@ class Run(BaseCommand):
             default="{}".format(
                 sys.executable if sys.executable else "/usr/bin/python"
             ),
-            help=("Python interpreter for Ansible execution. "))
+            help=("Python interpreter for Ansible execution."))
 
         parser.add_argument(
             '--extra-env-vars',
             action=KeyValueAction,
             default=None,
-            metavar="key1=<val1> [--extra-vars key3=<val3>]",
+            metavar="key1=<val1> [--extra-env-vars key2=<val2>]",
             help=(
-                " Add extra environment variables you may need "
+                "Add extra environment variables you may need "
                 "to provide to your Ansible execution "
                 "as KEY=VALUE pairs. Note that if you pass the same "
                 "KEY multiple times, the last given VALUE for that same KEY "
@@ -98,7 +101,7 @@ class Run(BaseCommand):
         extra_vars_group.add_argument(
             '--extra-vars',
             default=None,
-            metavar="key1=<val1> [--extra-vars key3=<val3>]",
+            metavar="key1=<val1> [--extra-vars key2=<val2>]",
             action=KeyValueAction,
             help=(
                 "Add Ansible extra variables to the validation(s) execution "
@@ -109,11 +112,11 @@ class Run(BaseCommand):
         extra_vars_group.add_argument(
             '--extra-vars-file',
             action='store',
+            metavar="/tmp/my_vars_file.[json|yaml]",
             default=None,
             help=(
-                "Add a JSON/YAML file containing extra variable "
+                "Absolute or relative Path to a JSON/YAML file containing extra variable(s) "
-                "to a validation: "
+                "to pass to one or multiple validation(s) execution."))
-                "--extra-vars-file /home/stack/vars.[json|yaml]."))
 
         ex_group = parser.add_mutually_exclusive_group(required=True)
         ex_group.add_argument(
@@ -124,20 +127,16 @@ class Run(BaseCommand):
             default=[],
             help=("Run specific validations, "
                   "if more than one validation is required "
-                  "separate the names with commas: "
+                  "separate the names with commas."))
-                  "--validation check-ftype,512e | "
-                  "--validation 512e"))
 
         ex_group.add_argument(
             '--group', '-g',
-            metavar='<group>[,<group>,...]',
+            metavar='<group_id>[,<group_id>,...]',
             action=CommaListAction,
             default=[],
             help=("Run specific group validations, "
                   "if more than one group is required "
-                  "separate the group names with commas: "
+                  "separate the group names with commas."))
-                  "--group pre-upgrade,prep | "
-                  "--group openshift-on-openstack"))
 
         ex_group.add_argument(
             '--category',

validations_libs/cli/show.py

@@ -23,7 +23,7 @@ from validations_libs.cli.parseractions import CommaListAction
 
 
 class Show(ShowOne):
-    """Validation Show client implementation class"""
+    """Show detailed informations about a Validation"""
 
     def get_parser(self, parser):
         """Argument parser for validation show"""
@@ -52,7 +52,7 @@ class Show(ShowOne):
 
 
 class ShowGroup(Lister):
-    """Validation Show group client implementation class"""
+    """Show detailed informations about Validation Groups"""
 
     def get_parser(self, parser):
         """Argument parser for validation show group"""
@@ -73,7 +73,12 @@ class ShowGroup(Lister):
 
 
 class ShowParameter(ShowOne):
-    """Display Validations Parameters"""
+    """Show Validation(s) parameter(s)
+
+    Display Validation(s) Parameter(s) which could be overriden during an
+    execution. It could be filtered by **validation_id**, **group(s)**,
+    **category(ies)** or by **products**.
+    """
 
     def get_parser(self, parser):
         parser = super(ShowParameter, self).get_parser(parser)
@@ -92,9 +97,7 @@ class ShowParameter(ShowOne):
             default=[],
             help=("List specific validations, "
                   "if more than one validation is required "
-                  "separate the names with commas: "
+                  "separate the names with commas.")
-                  "--validation check-ftype,512e | "
-                  "--validation 512e")
         )
 
         ex_group.add_argument(
@@ -104,9 +107,7 @@ class ShowParameter(ShowOne):
             default=[],
             help=("List specific group validations, "
                   "if more than one group is required "
-                  "separate the group names with commas: "
+                  "separate the group names with commas.")
-                  "pre-upgrade,prep | "
-                  "openshift-on-openstack")
         )
 
         ex_group.add_argument(