diff --git a/doc/requirements.txt b/doc/requirements.txt index 5e47e760..865bdf63 100644 --- a/doc/requirements.txt +++ b/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 diff --git a/doc/source/cli.rst b/doc/source/cli.rst new file mode 100644 index 00000000..c41b1d85 --- /dev/null +++ b/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 +`. + +Output +------ + +Global Options +~~~~~~~~~~~~~~ + +.. autoprogram-cliff:: validations_libs.cli.app.ValidationCliApp + :application: validation + +Command Options +~~~~~~~~~~~~~~~ + +.. autoprogram-cliff:: validation.cli diff --git a/doc/source/conf.py b/doc/source/conf.py index a5bcb73a..0b9a41f3 100644 --- a/doc/source/conf.py +++ b/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' diff --git a/doc/source/index.rst b/doc/source/index.rst index 9783aa1d..e88217da 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -16,6 +16,7 @@ Contents readme contributing testing + cli reference/index Indices and tables diff --git a/validations_libs/cli/history.py b/validations_libs/cli/history.py index dba9ebe5..ff9dd866 100644 --- a/validations_libs/cli/history.py +++ b/validations_libs/cli/history.py @@ -30,7 +30,7 @@ class ListHistory(BaseLister): parser = super(ListHistory, self).get_parser(parser) parser.add_argument('--validation', - metavar="", + metavar="", 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) diff --git a/validations_libs/cli/lister.py b/validations_libs/cli/lister.py index 61408436..07a835b3 100644 --- a/validations_libs/cli/lister.py +++ b/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='[,,...]', + metavar='[,,...]', action=CommaListAction, default=[], help=("List specific group of validations, " "if more than one group is required " - "separate the group names with commas: " - "--group pre-upgrade,prep | " - "--group openshift-on-openstack")) + "separate the group names with commas.")) parser.add_argument('--category', metavar='[,,...]', action=CommaListAction, diff --git a/validations_libs/cli/run.py b/validations_libs/cli/run.py index 9661df98..a4e03371 100644 --- a/validations_libs/cli/run.py +++ b/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="[,,,...]", + 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," - "compute-1,compute-5\".")) + "run invocation.")) 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= [--extra-vars key3=]", + metavar="key1= [--extra-env-vars key2=]", 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= [--extra-vars key3=]", + metavar="key1= [--extra-vars key2=]", 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 " - "to a validation: " - "--extra-vars-file /home/stack/vars.[json|yaml].")) + "Absolute or relative Path to a JSON/YAML file containing extra variable(s) " + "to pass to one or multiple validation(s) execution.")) 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: " - "--validation check-ftype,512e | " - "--validation 512e")) + "separate the names with commas.")) ex_group.add_argument( '--group', '-g', - metavar='[,,...]', + metavar='[,,...]', action=CommaListAction, default=[], help=("Run specific group validations, " "if more than one group is required " - "separate the group names with commas: " - "--group pre-upgrade,prep | " - "--group openshift-on-openstack")) + "separate the group names with commas.")) ex_group.add_argument( '--category', diff --git a/validations_libs/cli/show.py b/validations_libs/cli/show.py index 029f2799..20abdc59 100644 --- a/validations_libs/cli/show.py +++ b/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: " - "--validation check-ftype,512e | " - "--validation 512e") + "separate the names with commas.") ) 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: " - "pre-upgrade,prep | " - "openshift-on-openstack") + "separate the group names with commas.") ) ex_group.add_argument(