Add documentation for dovetail tool

JIRA:DOVETAIL-28

Change-Id: I2478655d951a65a11f39e9ceba10969e56274cc3
Signed-off-by: Leo Wang <grakiss.wanglei@huawei.com>

3 files changed, 201 insertions, 0 deletions

diff --git a/docs/installationprocedure/feature.configuation.rst b/docs/installationprocedure/feature.configuation.rst
new file mode 100644
index 00000000..0bc4ae33
--- /dev/null
+++ b/docs/installationprocedure/feature.configuation.rst
@@ -0,0 +1,45 @@
+.. 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.
+
+Testcase Template Syntax
+=========================
+
+The testcases certification are defined in ``dovetail/dovetail/testcase``.
+Take testcase ``ipv6.tc001.yml`` as an example.
+
+Basic template syntax
+---------------------
+
+::
+
+  dovetail.ipv6.tc001:
+    name: dovetail.ipv6.tc001
+    objective: VIM ipv6 operations, to create/delete network, port and subnet in bulk operation
+    scripts:
+      type: functest
+      testcase: tempest_smoke_serial
+      sub_testcase_list:
+        - tempest.api.network.test_networks.BulkNetworkOpsIpV6Test.test_bulk_create_delete_network
+        - tempest.api.network.test_networks.BulkNetworkOpsIpV6Test.test_bulk_create_delete_port
+        - tempest.api.network.test_networks.BulkNetworkOpsIpV6Test.test_bulk_create_delete_subnet
+
+The testcase needs at least three keys named as 'name', 'objective' and 'scripts'. The whole
+dovetail project can just recognize testcases by the 'name' section, which here is
+'dovetail.ipv6.tc001'. The 'objective' describes what exactly this testcase does. In the
+'scripts' part, there are some subsections such as 'type', 'testcase' and 'sub_testcase_list'.
+Dovetail now supports two kinds of types, functest and yardstick. If you define the type as
+functest, then you need to give the functest testcase that you want to use. If the type is
+yardstick, then a yardstick testcase is needed. The 'sub_testcase_list' lists the sub_testcases
+that you put a high value on. Even though the whole testcase faild, we still think it passed
+when all the sub_testcases pass. The sub_testcase_list is just available for functest. When
+for yardstick testcase, retain 'sub_testcase_list' section and keep the content empty.
+
+::
+
+  sub_testcase_list:
+    -
+
+This is the definition of the dovetail testcases. They can just be tested by adding into
+scenarios such as ``cert/basic.yml``.
diff --git a/docs/installationprocedure/index.rst b/docs/installationprocedure/index.rst
new file mode 100644
index 00000000..9a755800
--- /dev/null
+++ b/docs/installationprocedure/index.rst
@@ -0,0 +1,14 @@
+.. 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.
+
+==================
+Dovetail Overview
+==================
+
+.. toctree::
+   :maxdepth: 2
+
+   installation.instruction
+   feature.configuation
diff --git a/docs/installationprocedure/installation.instruction.rst b/docs/installationprocedure/installation.instruction.rst
new file mode 100644
index 00000000..aa1b436a
--- /dev/null
+++ b/docs/installationprocedure/installation.instruction.rst
@@ -0,0 +1,142 @@
+.. 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.
+
+=====================
+Dovetail Installation
+=====================
+
+Abstract
+========
+
+Dovetail currently supports installation on Ubuntu 14.04 or by using a docker image.
+Detailed steps about installing dovetail can be found below.
+
+To use dovetail you should have access to an OpenStack environment,
+with at least Nova, Neutron, Glance, Keystone and Heat installed.
+
+
+Run dovetail on local machine
+=============================
+
+The steps needed to run dovetail on Ubuntu are:
+
+1. Download source code and prepare environment.
+2. Create certification configuration file.
+3. Run certification.
+
+
+Download dovetail and prepare environment
+-----------------------------------------
+
+The source code of dovetail can be got from Gerrit:
+
+::
+
+  git clone https://gerrit.opnfv.org/gerrit/dovetail
+
+After that you need to prepare the environment which means install some tools,
+modules and anything else dovetail needs. A file named ``prepare_env.py`` can
+do all of these for you.
+
+::
+
+  cd dovetail/dovetail/
+  python prepare_env.py
+
+Now the environment should be prepared for running the certification.
+
+Besides, you may want to install it in a python virtualenv, that is beyond the scope
+of this installation instruction.
+
+Create certification configuration file
+---------------------------------------
+
+You can wirte a certification configuration file with the format of yaml,
+which can be defined to meet your own requirements. The yaml file should
+be located in the folder ``dovetail/dovetail/cert``. There provide a sample
+file named ``basic.yml``.
+
+::
+
+  certification_basic:
+    name: certification_basic
+    testcase_list:
+      - dovetail.ipv6.tc001
+
+As you can see, the configuration file combines the testcases you want to run
+together, and all of them should already been defined in ``dovetail/dovetail/testcase``.
+The name of the configuration file should be certification_%s, where %s (here is basic)
+can be used to run this certification.
+
+
+Run the certification
+---------------------
+
+When you get the dovetail source code, prepare the environment and define the
+certification configuration file, you can then run the certification. Take
+certification_basic as the example. You can run it using the file ``run.py`` with
+basic (scenario name) as its argument.
+
+::
+
+  python run.py --scenario basic
+
+If you did not give an argument, it will be default set as basic.
+
+
+Run dovetail on Docker container
+================================
+
+steps:
+1. pull image
+2. run container
+3. config
+4. run testcase
+
+pull image
+----------
+
+Get the latest docker image from docker hub.
+
+::
+ sudo docker pull opnfv/dovetail:latest
+
+run container
+-------------
+
+Start a container from the image that you just pulled.
+
+::
+ sudo docker run -it --privileged=true -v /home/opnfv/dovetail/results:/home/opnfv/dovetail/results
+ -v /var/run/docker.sock:/var/run/docker.sock opnfv/dovetail:latest "/bin/bash"
+
+config
+------
+
+For now, we need only change value of ``INSTALLER_TYPE`` and ``INSTALLER_IP``
+of the variable ``envs`` to your own environment.
+
+::
+ sudo docker exec -it $(CONTAINER_ID) "/bin/bash"
+ vi /home/opnfv/dovetail/dovetail/conf/functest_config.yml
+ vi /home/opnfv/dovetail/dovetail/conf/yardstick_config.yml
+
+run testcase
+------------
+
+In docker, you just run following cmds to execute the testcase.
+
+::
+ cd /home/opnfv/dovetail/dovetail
+ python run.py
+
+
+
+
+Output
+======
+
+The running log is stored in ``/home/opnfv/dovetail/results/dovetail.log``.
+The report of certification is stored in ``/home/opnfv/dovetail/results/dovetail_report.txt``.