Reorganize existing documents

- Align document structure with Colorado release
- follow convention used in "Python’s Style Guide for documentating"[1]

[1] https://docs.python.org/devguide/documenting.html#sections

Change-Id: Idee6ad6e68a35e3fd84ec36de480722e0259011b
JIRA: QTIP-117
Signed-off-by: Yujun Zhang <zhang.yujunz@zte.com.cn>

9 files changed, 91 insertions, 42 deletions

diff --git a/docs/userguide/01-compute.rst b/docs/userguide/_01-compute.rst
index 7a2f09f5..7cd4c2ce 100644
--- a/docs/userguide/01-compute.rst
+++ b/docs/userguide/_01-compute.rst
@@ -4,9 +4,8 @@
 .. (c) 2016 ZTE Corp.
 
 
-Compute test cases
-==================
-
+Compute Suite
+=============
 
 Introduction
 ------------
diff --git a/docs/userguide/02-network.rst b/docs/userguide/_02-network.rst
index c556642b..13697aba 100644
--- a/docs/userguide/02-network.rst
+++ b/docs/userguide/_02-network.rst
@@ -4,8 +4,8 @@
 .. (c) 2016 ZTE Corp.
 
 
-Network test cases
-==================
+Network Suite
+=============
 
 QTIP uses IPerf3 as the main tool for testing the network throughput.
 There are three tests that are run through the QTIP framework.
diff --git a/docs/userguide/03-storage.rst b/docs/userguide/_03-storage.rst
index ea3bb4f3..b1490432 100644
--- a/docs/userguide/03-storage.rst
+++ b/docs/userguide/_03-storage.rst
@@ -4,8 +4,8 @@
 .. (c) 2016 ZTE Corp.
 
 
-Storage test cases
-==================
+Storage Suite
+=============
 
 The QTIP benchmark suite aims to evaluate storage components within an OPNFV platform.
 For Brahamaputra release, FIO would evaluate File System performance for the host machine.
diff --git a/docs/userguide/_testcase_description.rst b/docs/userguide/_testcase_description.rst
new file mode 100644
index 00000000..d60ca949
--- /dev/null
+++ b/docs/userguide/_testcase_description.rst
@@ -0,0 +1,46 @@
+.. Template to be used for test case descriptions in QTIP Project.
+   Write one .rst per test case.
+   Borrowed Heavily from Yardstick
+   Upload the .rst for the test case in /docs/ directory.
+   Review in Gerrit.
+
+Test Case Description
+=====================
+
++-----------------------------------------------------------------------------+
+|test case slogan e.g. Network throughput                                     |
++==============+==============================================================+
+|test case id  | e.g. qtip_throughput                                         |
++--------------+--------------------------------------------------------------+
+|metric        | what will be measured, e.g. latency                          |
++--------------+--------------------------------------------------------------+
+|test purpose  | describe what is the purpose of the test case                |
++--------------+--------------------------------------------------------------+
+|configuration | what .yaml file to use, state SLA if applicable, state       |
+|              | test duration, list and describe the scenario options used in|
+|              | this TC and also list the options using default values.      |
++--------------+--------------------------------------------------------------+
+|test tool     | e.g. ping                                                    |
++--------------+--------------------------------------------------------------+
+|references    | e.g. RFCxxx, ETSI-NFVyyy                                     |
++--------------+--------------------------------------------------------------+
+|applicability | describe variations of the test case which can be            |
+|              | performend, e.g. run the test for different packet sizes     |
++--------------+--------------------------------------------------------------+
+|pre-test      | describe configuration in the tool(s) used to perform        |
+|conditions    | the measurements (e.g. fio, pktgen), POD-specific            |
+|              | configuration required to enable running the test            |
++--------------+------+----------------------------------+--------------------+
+|test sequence | step | description                      | result             |
+|              +------+----------------------------------+--------------------+
+|              |  1   | use this to describe tests that  | what happens in    |
+|              |      | require several steps e.g.       | this step          |
+|              |      | step 1 collect logs              | e.g. logs collected|
+|              +------+----------------------------------+--------------------+
+|              |  2   | remove interface                 | interface down     |
+|              +------+----------------------------------+--------------------+
+|              |  N   | what is done in step N           | what happens       |
++--------------+------+----------------------------------+--------------------+
+|test verdict  | expected behavior, or SLA, pass/fail criteria                |
++--------------+--------------------------------------------------------------+
+
diff --git a/docs/userguide/annex.rst b/docs/userguide/annex.rst
new file mode 100644
index 00000000..406d5132
--- /dev/null
+++ b/docs/userguide/annex.rst
@@ -0,0 +1,19 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) 2016 ZTE Corp.
+
+
+*****
+Annex
+*****
+
+Templates
+=========
+
+.. include:: _testcase_description.rst
+
+
+Downloads
+=========
+
+- :download:`Sample configuration <../download/sample_config.yaml>`
\ No newline at end of file
diff --git a/docs/userguide/benchmark-suites.rst b/docs/userguide/benchmark-suites.rst
new file mode 100644
index 00000000..9a3929cc
--- /dev/null
+++ b/docs/userguide/benchmark-suites.rst
@@ -0,0 +1,12 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) 2016 ZTE Corp.
+
+
+****************
+Benchmark Suites
+****************
+
+.. include:: _01-compute.rst
+.. include:: _02-network.rst
+.. include:: _03-storage.rst
diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst
index 202bf66e..3032f357 100644
--- a/docs/userguide/index.rst
+++ b/docs/userguide/index.rst
@@ -4,18 +4,13 @@
 .. (c) 2016 ZTE Corp.
 
 
-**************
-QTIP Userguide
-**************
-
-Colorado 1.0
-------------
+===============
+QTIP User Guide
+===============
 
 .. toctree::
    :maxdepth: 2
 
-   ./overview.rst
    ./introduction.rst
-   ./01-compute.rst
-   ./02-network.rst
-   ./03-storage.rst
+   ./benchmark-suites.rst
+   ./annex.rst
diff --git a/docs/userguide/introduction.rst b/docs/userguide/introduction.rst
index b874ea46..2655347e 100644
--- a/docs/userguide/introduction.rst
+++ b/docs/userguide/introduction.rst
@@ -4,9 +4,9 @@
 .. (c) 2016 ZTE Corp.
 
 
-*****************
-Qtip Introduction
-*****************
+************
+Introduction
+************
 
 This guide will serve as a first step to familiarize the user with how to
 run QTIP the first time when the user clones QTIP on to their host machine.
diff --git a/docs/userguide/overview.rst b/docs/userguide/overview.rst
deleted file mode 100644
index 82b7de91..00000000
--- a/docs/userguide/overview.rst
+++ /dev/null
@@ -1,22 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) 2015 Dell Inc.
-.. (c) 2016 ZTE Corp.
-
-
-********
-Overview
-********
-
-.. _QTIP: https://wiki.opnfv.org/platform_performance_benchmarking
-
-QTIP_ is an OPNFV Project.
-
-QTIP aims to benchmark OPNFV platforms through a "Bottom up" approach, testing
-bare-metal components first.
-
-The overall problem this project tries to solve is the general
-characterization of an OPNFV platform. It will focus on general performance
-questions that are common to the platform itself, or applicable to multiple
-OPNFV use cases. QTIP will provide the capability to quantify a platform's
-performance behavior in a standardized, rigorous, and open way.