Document CLI options

Change-Id: Iee1ba9ed82fd8bab88fffc96e292a5336082d884
Story: 2002703
Task: 22570

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
+                        help="""Path to deployer file
-                                override the default values. The
+                                A file in the format of tempest.conf that will
-                                deployer-input file is an alternative to
+                                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
+                        help="""Override options
-                                section.key where section is a section header
+                                Key value pairs used to hardcode values in
-                                in the conf file.
+                                `tempest.conf`. The key is a section.key where
-                                For example: identity.username myname
+                                section is a section header in the conf file.
-                                 identity.password mypass""")
+                                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
+                        metavar='PATH',
-                        in the specified 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
+                        help="""Specify which network with external connectivity
-                                instance 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
+                                For example:
-                                --remove feature-enabled.api_ext=http,https""")
+                                 $ discover-tempest-config \\
+                                  --remove identity.username=myname \\
+                                  --remove feature-enabled.api_ext=http,https
+                             """)
     return parser
 
 

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

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
+

doc/source/cli/index.rst

@@ -0,0 +1,8 @@
+CLI Documentation
+=================
+
+.. toctree::
+  :maxdepth: 2
+  :includehidden:
+
+  cli_options

doc/source/conf.py

@@ -20,7 +20,8 @@
 extensions = [
     'openstackdocstheme',
     #'sphinx.ext.intersphinx',
-    'sphinx.ext.autodoc'
+    'sphinx.ext.autodoc',
+    'sphinxarg.ext'
 ]
 
 html_theme = 'openstackdocs'

doc/source/index.rst

@@ -17,6 +17,7 @@ Content:
 
    overview
    install/index
+   cli/index
    user/index
    contributor/index