From 35fc18edd847ce53742496d73e6076dadce7b164 Mon Sep 17 00:00:00 2001
From: xudan <xudan16@huawei.com>
Date: Wed, 7 Dec 2016 06:21:58 +0000
Subject: dovetail tool: document for dovetail CLI
1. document for developers about how to add or delete commands by modifying
cmd_config.yml file.
2. document for users about how to run dovetail tool with CLI
JIRA: DOVETAIL-25
Change-Id: Iecf9d7a230e694bdda5634a87f7e5ddf7b7a57fd
Signed-off-by: xudan <xudan16@huawei.com>
---
docs/dovetailtool/dovetail.tool.cli.rst | 180 ++++++++++++++++++++++++++++++++
docs/dovetailtool/index.rst | 1 +
2 files changed, 181 insertions(+)
create mode 100644 docs/dovetailtool/dovetail.tool.cli.rst
diff --git a/docs/dovetailtool/dovetail.tool.cli.rst b/docs/dovetailtool/dovetail.tool.cli.rst
new file mode 100644
index 00000000..bdcf46e4
--- /dev/null
+++ b/docs/dovetailtool/dovetail.tool.cli.rst
@@ -0,0 +1,180 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) OPNFV, Huawei Technologies Co.,Ltd and others.
+
+Command Line Interface
+======================
+
+Dovetail supports modifying some parameters at the run-time by using the command
+line interface (CLI). The parameters can be defined through a config file by
+developers easily and then be used at the run-time.
+
+The CLI now fits all three kinds of running: directly running the python script,
+running after setup and running within Docker containers.
+
+Define CLI with config file
+---------------------------
+
+For easy to be modified, Dovetail provides ``dovetail/dovetail/conf/cmd_config.yml``
+to define CLI automatically.
+
+::
+
+ cli:
+ arguments:
+ config:
+ # This is a simple example of arguments.
+ # Dovetail has no need of this kind of parameters currently.
+ # The arguments must be given orderly at the run-time.
+ #
+ # docker_tag:
+ # flags: 'docker_tag'
+ # path:
+ # - 'functest/docker_tag'
+ # - 'yardstick/docker_tag'
+ control:
+
+ options:
+ config:
+ SUT_TYPE:
+ flags:
+ - '--SUT_TYPE'
+ - '-t'
+ path:
+ - 'functest/envs'
+ - 'yardstick/envs'
+ help: 'Installer type of the system under test (SUT).'
+ yard_tag:
+ flags:
+ - '--yard_tag'
+ - '-y'
+ path:
+ - 'yardstick/docker_tag'
+ help: 'Overwrite tag for yardstick docker container (e.g. stable or latest)'
+ func_tag:
+ flags:
+ - '--func_tag'
+ - '-f'
+ path:
+ - 'functest/docker_tag'
+ help: 'Overwrite tag for functest docker container (e.g. stable or latest)'
+ control:
+ testsuite:
+ flags:
+ - '--testsuite'
+ default: 'compliance_set'
+ help: 'compliance testsuite.'
+ testarea:
+ flags:
+ - '--testarea'
+ default: 'full'
+ help: 'compliance testarea within testsuite'
+
+Dovetail uses click module in python to parse parameters defined in the above
+config file. The basic config file shown above contains two subsections:
+**arguments** and **options** corresponding to two types of parameters in click.
+
+Add options
++++++++++++
+
+Just as the name suggested, option parameters can either be given or not by users
+after adding into CLI.
+
+Then how to add an option for developers?
+
+For each option, it at least needs a key **flags** to give its name. Customarily,
+each option has two names, full name and short name, and they are begin with '--'
+and '-' respectively. All other keys should be consistent with click's keys.
+
+Take option **scenario** as the example. Its full name is '--scenario', and its
+short name is '-s'. Actually full name is necessary but short name is optional.
+The full name '--scenario' should be the same with the block's name **scenario**.
+**default** section gives the default value of this option if it doesn't given
+by users. Without the **default** section, it will be set None. **help** section
+offers its help message that will be shown when excute -h/--help command. For
+more information about click, please refer to: http://click.pocoo.org/5/
+
+Add arguments
++++++++++++++
+
+Arguments must given orderly by users once they are defined in the config file.
+The Dovetail tool doesn't need any argument parameters currently. However, here
+just give a simple example for its format.
+
+Arguments also need subsection **flags** to give its name. Each argument can just
+have one name, and the name should be the same with the key of this section. Other
+keys should also be consistent with the click module.
+
+Config and control
+++++++++++++++++++
+
+All options/arguments are divided into two parts: **config** and **control**.
+The config ones are used for updating functest or yardstick config files according
+to the **path** given. For example, functest's config file is
+``dovetail/dovetail/conf/functest_config.yml``, following is a simple example:
+
+::
+
+ docker_tag: latest
+ envs: '-e INSTALLER_TYPE=compass -e INSTALLER_IP=192.168.200.2
+ -e NODE_NAME=dovetail-pod -e DEPLOY_SCENARIO=ha_nosdn
+ -e BUILD_TAG=dovetail -e CI_DEBUG=true -e DEPLOY_TYPE=baremetal'
+
+If running with the command ``python run.py --SUT_TYPE fuel -f stable``, then
+the configs will be changed into
+
+::
+
+ docker_tag: stable
+ envs: '-e INSTALLER_TYPE=fuel -e INSTALLER_IP=192.168.200.2
+ -e NODE_NAME=dovetail-pod -e DEPLOY_SCENARIO=ha_nosdn
+ -e BUILD_TAG=dovetail -e CI_DEBUG=true -e DEPLOY_TYPE=baremetal'
+
+The config options/arguments can be added or deleted just by modifying
+``cmd_config.yml`` rather than changing the source code. However, for control
+command, besides adding it into ``cmd_config.yml``, some other operations about
+the source code are also needed.
+
+Run with CLI
+------------
+
+For users, they can use CLI to input their own envs at the run-time instead of
+modifying the config files of functest or yardstick. So Dovetail can supports
+different environments more flexible with CLI. Dovetail now can be run with three
+methods, directly running ``run.py`` script, running after setup and running
+in Docker containers. The uses of CLI are almost the same for these three methods
+and here take the first one as the example.
+
+All parameters offered by Dovetail can be listed by using help option ``--help``.
+
+::
+
+ root@90256c4efd05:~/dovetail/dovetail$ python run.py --help
+ Usage: run.py [OPTIONS]
+
+ Dovetail compliance test entry!
+
+ Options:
+ -t, --SUT_TYPE TEXT Installer type of the system under test (SUT).
+ -f, --func_tag TEXT Overwrite tag for functest docker container (e.g.
+ stable or latest)
+ -i, --SUT_IP TEXT IP of the system under test (SUT).
+ -y, --yard_tag TEXT Overwrite tag for yardstick docker container (e.g.
+ stable or latest)
+ -d, --DEBUG TEXT DEBUG for showing debug log.
+ --testarea TEXT compliance testarea within testsuite
+ --testsuite TEXT compliance testsuite.
+ -h, --help Show this message and exit.
+
+All options listed can be used to input special environment values at the run-time.
+For example:
+
+::
+
+ python run.py --SUT_TYPE compass -y stable
+
+There is no need to give all these options. If it is not given by CLI, it will
+be set with the system's environment value. If it is not included in system's
+environment variables, it will be set with the default value in functest/yardstick
+config file.
diff --git a/docs/dovetailtool/index.rst b/docs/dovetailtool/index.rst
index a025cd50..f528a4f7 100644
--- a/docs/dovetailtool/index.rst
+++ b/docs/dovetailtool/index.rst
@@ -14,3 +14,4 @@ Dovetail Overview
dovetail.tool.installation.rst
dovetail.tool.configuation.rst
dovetail.tool.configtemplate.rst
+ dovetail.tool.cli.rst
--
cgit