openstack/validations-libs
Code Issues Proposed changes

Add CLI auto generated documentation using Cliff

Browse Source 
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>
This commit is contained in:
Gael Chamoulaud (Strider) 2021-07-21 15:21:55 +02:00 committed by Gael Chamoulaud
parent c46c90394c
commit e4b5dc3ea7
8 changed files with 58 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/requirements.txt
View File

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

22
doc/source/cli.rst Normal file
View File

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

2
doc/source/conf.py
View File

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

1
doc/source/index.rst
View File

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

4
validations_libs/cli/history.py
View File

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

8
validations_libs/cli/lister.py
View File

@ -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: "
"--group pre-upgrade,prep | "
"--group openshift-on-openstack"))
"separate the group names with commas."))
parser.add_argument('--category',
metavar='<category_id>[,<category_id>,...]',
action=CommaListAction,

35
validations_libs/cli/run.py
View File

@ -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,"
"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=<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 "
"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='<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: "
"--group pre-upgrade,prep | "
"--group openshift-on-openstack"))
"separate the group names with commas."))
ex_group.add_argument(
'--category',

19
validations_libs/cli/show.py
View File

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