From 3b4c3f7bdc101182f6ff2d8e18cc21f1921b5acb Mon Sep 17 00:00:00 2001 From: Martin Kopec Date: Mon, 9 Jul 2018 09:51:13 +0000 Subject: [PATCH] Document CLI options Change-Id: Iee1ba9ed82fd8bab88fffc96e292a5336082d884 Story: 2002703 Task: 22570 --- config_tempest/main.py | 82 +++++++++++++++++++++++----------- doc/requirements.txt | 1 + doc/source/cli/cli_options.rst | 12 +++++ doc/source/cli/index.rst | 8 ++++ doc/source/conf.py | 3 +- doc/source/index.rst | 1 + 6 files changed, 81 insertions(+), 26 deletions(-) create mode 100644 doc/source/cli/cli_options.rst create mode 100644 doc/source/cli/index.rst diff --git a/config_tempest/main.py b/config_tempest/main.py index 452f427f..9d505068 100755 --- a/config_tempest/main.py +++ b/config_tempest/main.py @@ -214,41 +214,69 @@ def get_arg_parser(): cloud_config = os_client_config.OpenStackConfig() cloud_config.register_argparse_arguments(parser, sys.argv) parser.add_argument('--create', action='store_true', default=False, - help='create default tempest resources') + help="""Create Tempest resources + Make *python-tempestconf* to create Tempest + resources such as flavors needed for running + Tempest tests.""") parser.add_argument('--out', default="etc/tempest.conf", - help='the tempest.conf file to write') + help="""Output file + A name of the file where the discovered Tempest + configuration will be written to.""") parser.add_argument('--deployer-input', default=None, - help="""A file in the format of tempest.conf that will - override the default values. The - deployer-input file is an alternative to + help="""Path to deployer file + A file in the format of tempest.conf that will + override the default values. It is usually + created by an installer and contains + environment specific options. + + The deployer-input file is an alternative to providing key/value pairs. If there are also key/value pairs they will be applied after the deployer-input file. - """) + + If the option is **not defined** and + **--no-default-deployer** is **not used**, + python-tempestconf **will try** to look for the + file in `$HOME/tempest-deployer-input.conf` + location.""") parser.add_argument('--no-default-deployer', action='store_true', default=False, help="""Do not check for the default deployer input in - $home/tempest-deployer-input.conf - """) + `$HOME/tempest-deployer-input.conf`""") parser.add_argument('overrides', nargs='*', default=[], - help="""key value pairs to modify. The key is - section.key where section is a section header - in the conf file. - For example: identity.username myname - identity.password mypass""") + help="""Override options + Key value pairs used to hardcode values in + `tempest.conf`. The key is a section.key where + section is a section header in the conf file. + For example: + $ discover-tempest-config \\ + identity.username myname \\ + identity.password mypass""") parser.add_argument('--debug', action='store_true', default=False, - help='Print debugging information') + help='Print debugging information.') parser.add_argument('--verbose', '-v', action='store_true', default=False, - help='Print more information about the execution') + help='Print more information about the execution.') parser.add_argument('--non-admin', action='store_true', default=False, - help='Run without admin creds') + help="""Simulate non-admin credentials. + When True, the credentials are used as + non-admin ones. No resources are created.""") parser.add_argument('--test-accounts', default=None, metavar='PATH', - help='Use accounts from accounts.yaml') + help="""Tempest accounts.yaml file + Defines a path to a Tempest accounts.yaml + file. + For example: + --test-accounts $HOME/tempest/accounts.yaml + """) parser.add_argument('--create-accounts-file', default=None, - metavar='PATH', help="""Generate test accounts file - in the specified path.""") + metavar='PATH', + help="""Generate Tempest accounts file + Minimal accounts file will be created in the + specified path. + For example: + --create-accounts-file $HOME/accounts.yaml + """) parser.add_argument('--image-disk-format', default=C.DEFAULT_IMAGE_FORMAT, - help="""a format of an image to be uploaded to glance. + help="""A format of an image to be uploaded to glance. Default is '%s'""" % C.DEFAULT_IMAGE_FORMAT) parser.add_argument('--image', default=C.DEFAULT_IMAGE, help="""An image name/path/url to be uploaded to @@ -256,14 +284,18 @@ def get_arg_parser(): the image is the leaf name of the path. Default is '%s'""" % C.DEFAULT_IMAGE) parser.add_argument('--network-id', - help="""The ID of an existing network in our openstack - instance with external connectivity""") + help="""Specify which network with external connectivity + should be used by the tests.""") parser.add_argument('--remove', action='append', default=[], metavar="SECTION.KEY=VALUE[,VALUE]", - help="""key value pair to be removed from + help="""Remove values from tempest.conf + Key value pair to be removed from the configuration file. - For example: --remove identity.username=myname - --remove feature-enabled.api_ext=http,https""") + For example: + $ discover-tempest-config \\ + --remove identity.username=myname \\ + --remove feature-enabled.api_ext=http,https + """) return parser diff --git a/doc/requirements.txt b/doc/requirements.txt index 743d92a3..c6b3b63f 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,3 +1,4 @@ openstackdocstheme>=1.20.0 # Apache-2.0 reno>=1.8.0 # Apache-2.0 sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD +sphinx-argparse>=0.2.2 # MIT diff --git a/doc/source/cli/cli_options.rst b/doc/source/cli/cli_options.rst new file mode 100644 index 00000000..f8c3ead8 --- /dev/null +++ b/doc/source/cli/cli_options.rst @@ -0,0 +1,12 @@ +=========== +CLI Options +=========== + +discover-tempest-config +----------------------- + +.. argparse:: + :filename: config_tempest/main.py + :func: get_arg_parser + :prog: discover-tempest-config + diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst new file mode 100644 index 00000000..2a45ebbf --- /dev/null +++ b/doc/source/cli/index.rst @@ -0,0 +1,8 @@ +CLI Documentation +================= + +.. toctree:: + :maxdepth: 2 + :includehidden: + + cli_options diff --git a/doc/source/conf.py b/doc/source/conf.py index 2d0f9879..1a596f91 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -20,7 +20,8 @@ extensions = [ 'openstackdocstheme', #'sphinx.ext.intersphinx', - 'sphinx.ext.autodoc' + 'sphinx.ext.autodoc', + 'sphinxarg.ext' ] html_theme = 'openstackdocs' diff --git a/doc/source/index.rst b/doc/source/index.rst index 24ae6561..a40edc89 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -17,6 +17,7 @@ Content: overview install/index + cli/index user/index contributor/index