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>
This commit is contained in:
Gael Chamoulaud (Strider)
Gael Chamoulaud
parent
c46c90394c
commit
e4b5dc3ea7
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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'
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@ Contents
|
|||
readme
|
||||
contributing
|
||||
testing
|
||||
cli
|
||||
reference/index
|
||||
|
||||
Indices and tables
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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',
|
||||
|
|
|
|||
|
|
@ -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(
|
||||
|
|
|
|||
Loading…
Reference in New Issue