Merge "[docs] Update header levels"

8 files changed, 115 insertions, 53 deletions

diff --git a/docs/release/results/euphrates_fraser_comparison.rst b/docs/release/results/euphrates_fraser_comparison.rst
index 53dfb994f..1dd328bb7 100644
--- a/docs/release/results/euphrates_fraser_comparison.rst
+++ b/docs/release/results/euphrates_fraser_comparison.rst
@@ -2,7 +2,15 @@
 .. License.
 .. http://creativecommons.org/licenses/by/4.0
 
-=======================================================
+..
+      Convention for heading levels in Yardstick:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ^^^^^^^  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      Avoid deeper levels because they do not render well.
+
 Test results analysis for Euphrates and Fraser releases
 =======================================================
 
diff --git a/docs/release/results/overview.rst b/docs/release/results/overview.rst
index 9fd74797c..b5e6a43a6 100644
--- a/docs/release/results/overview.rst
+++ b/docs/release/results/overview.rst
@@ -3,6 +3,15 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. (c) OPNFV, Ericsson AB and others.
 
+..
+      Convention for heading levels in Yardstick:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ^^^^^^^  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      Avoid deeper levels because they do not render well.
+
 Yardstick test tesult document overview
 =======================================
 
diff --git a/docs/release/results/results.rst b/docs/release/results/results.rst
index a63d84f21..f0c20360b 100644
--- a/docs/release/results/results.rst
+++ b/docs/release/results/results.rst
@@ -2,8 +2,17 @@
 .. License.
 .. http://creativecommons.org/licenses/by/4.0
 
+..
+      Convention for heading levels in Yardstick:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ^^^^^^^  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      Avoid deeper levels because they do not render well.
+
 Results listed by test cases
-==========================
+----------------------------
 
 .. _TOM: https://wiki.opnfv.org/display/testing/R+post-processing+of+the+Yardstick+results
 
@@ -14,7 +23,7 @@ the determined state of the specific test case as executed in the Fraser release
 process. All test date are analyzed using TOM_ tool.
 
 Scenario Results
-================
+----------------
 
 .. _Dashboard: http://testresults.opnfv.org/grafana/dashboard/db/yardstick-main
 .. _Jenkins: https://build.opnfv.org/ci/view/yardstick/
@@ -42,7 +51,7 @@ Test results of executed tests are avilable in Dashboard_ and logs in Jenkins_.
 Test results for Fraser release are collected from April 10, 2018 to May 13, 2018.
 
 Feature Test Results
-====================
+--------------------
 
 The following features were verified by Yardstick test cases:
 
diff --git a/docs/templates/test_results_template.rst b/docs/templates/test_results_template.rst
index f04b2b2a8..4523563a1 100644
--- a/docs/templates/test_results_template.rst
+++ b/docs/templates/test_results_template.rst
@@ -1,3 +1,18 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License.
+.. http://creativecommons.org/licenses/by/4.0
+
+..
+   Convention for heading levels in Yardstick documentation:
+
+   =======  Heading 0 (reserved for the title in a document)
+   -------  Heading 1
+   ~~~~~~~  Heading 2
+   +++++++  Heading 3
+   '''''''  Heading 4
+
+   Avoid deeper levels because they do not render well.
+
 =====================
 Yardstick Test Report
 =====================
diff --git a/docs/testing/user/userguide/04-installation.rst b/docs/testing/user/userguide/04-installation.rst
index d97078909..6b3259299 100644
--- a/docs/testing/user/userguide/04-installation.rst
+++ b/docs/testing/user/userguide/04-installation.rst
@@ -3,6 +3,17 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. (c) OPNFV, Ericsson AB, Huawei Technologies Co.,Ltd and others.
 
+..
+   Convention for heading levels in Yardstick documentation:
+
+   =======  Heading 0 (reserved for the title in a document)
+   -------  Heading 1
+   ~~~~~~~  Heading 2
+   +++++++  Heading 3
+   '''''''  Heading 4
+
+   Avoid deeper levels because they do not render well.
+
 ======================
 Yardstick Installation
 ======================
diff --git a/docs/testing/user/userguide/09-api.rst b/docs/testing/user/userguide/09-api.rst
index f0ae3980b..1a896699b 100644
--- a/docs/testing/user/userguide/09-api.rst
+++ b/docs/testing/user/userguide/09-api.rst
@@ -433,7 +433,7 @@ Example::
 
 
 /api/v2/yardstick/tasks/<task_id>
---------------------------------
+---------------------------------
 
 Description: This API is used to do some work related to yardstick tasks. For Euphrates, it supports:
 
diff --git a/docs/testing/user/userguide/13-nsb-installation.rst b/docs/testing/user/userguide/13-nsb-installation.rst
index 0b76cdd30..363ad4852 100644
--- a/docs/testing/user/userguide/13-nsb-installation.rst
+++ b/docs/testing/user/userguide/13-nsb-installation.rst
@@ -3,12 +3,23 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. (c) OPNFV, 2016-2017 Intel Corporation.
 
+..
+   Convention for heading levels in Yardstick documentation:
+
+   =======  Heading 0 (reserved for the title in a document)
+   -------  Heading 1
+   ~~~~~~~  Heading 2
+   +++++++  Heading 3
+   '''''''  Heading 4
+
+   Avoid deeper levels because they do not render well.
+
 =====================================
 Yardstick - NSB Testing -Installation
 =====================================
 
 Abstract
-========
+--------
 
 The Network Service Benchmarking (NSB) extends the yardstick framework to do
 VNF characterization and benchmarking in three different execution
@@ -27,7 +38,7 @@ The steps needed to run Yardstick with NSB testing are:
 
 
 Prerequisites
-=============
+-------------
 
 Refer chapter Yardstick Installation for more information on yardstick
 prerequisites
@@ -46,7 +57,7 @@ Several prerequisites are needed for Yardstick (VNF testing):
   * intel-cmt-cat
 
 Hardware & Software Ingredients
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 SUT requirements:
 
@@ -85,7 +96,7 @@ Boot and BIOS settings:
 
 
 Install Yardstick (NSB Testing)
-===============================
+-------------------------------
 
 Download the source code and install Yardstick from it
 
@@ -172,8 +183,8 @@ Another way to execute an installation for a Bare-Metal or a Standalone context
 is to use ansible script ``install.yaml``. Refer chapter :doc:`04-installation`
 for more details.
 
-System Topology:
-================
+System Topology
+---------------
 
 .. code-block:: console
 
@@ -188,10 +199,10 @@ System Topology:
 
 
 Environment parameters and credentials
-======================================
+--------------------------------------
 
 Config yardstick conf
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 If user did not run 'yardstick env influxdb' inside the container, which will
 generate correct ``yardstick.conf``, then create the config file manually (run
@@ -222,11 +233,11 @@ Add trex_path, trex_client_lib and bin_path in 'nsb' section.
   trex_client_lib=/opt/nsb_bin/trex_client/stl
 
 Run Yardstick - Network Service Testcases
-=========================================
+-----------------------------------------
 
 
 NS testing - using yardstick CLI
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
   See :doc:`04-installation`
 
@@ -239,13 +250,13 @@ NS testing - using yardstick CLI
   yardstick --debug task start yardstick/samples/vnf_samples/nsut/<vnf>/<test case>
 
 Network Service Benchmarking - Bare-Metal
-=========================================
+-----------------------------------------
 
 Bare-Metal Config pod.yaml describing Topology
-----------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Bare-Metal 2-Node setup
-^^^^^^^^^^^^^^^^^^^^^^^
++++++++++++++++++++++++
 .. code-block:: console
 
   +----------+              +----------+
@@ -258,7 +269,7 @@ Bare-Metal 2-Node setup
   trafficgen_1                   vnf
 
 Bare-Metal 3-Node setup - Correlated Traffic
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+++++++++++++++++++++++++++++++++++++++++++++
 .. code-block:: console
 
   +----------+              +----------+            +------------+
@@ -273,7 +284,7 @@ Bare-Metal 3-Node setup - Correlated Traffic
 
 
 Bare-Metal Config pod.yaml
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 Before executing Yardstick test cases, make sure that pod.yaml reflects the
 topology and update all the required fields.::
 
@@ -348,13 +359,13 @@ topology and update all the required fields.::
 
 
 Network Service Benchmarking - Standalone Virtualization
-========================================================
+--------------------------------------------------------
 
 SR-IOV
-------
+~~~~~~
 
 SR-IOV Pre-requisites
-^^^^^^^^^^^^^^^^^^^^^
++++++++++++++++++++++
 
 On Host, where VM is created:
  a) Create and configure a bridge named ``br-int`` for VM to connect to external network.
@@ -425,10 +436,10 @@ On Host, where VM is created:
 
 
 SR-IOV Config pod.yaml describing Topology
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+++++++++++++++++++++++++++++++++++++++++++
 
-SR-IOV 2-Node setup:
-^^^^^^^^^^^^^^^^^^^^
+SR-IOV 2-Node setup
++++++++++++++++++++
 .. code-block:: console
 
                                +--------------------+
@@ -456,7 +467,7 @@ SR-IOV 2-Node setup:
 
 
 SR-IOV 3-Node setup - Correlated Traffic
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+++++++++++++++++++++++++++++++++++++++++
 .. code-block:: console
 
                                +--------------------+
@@ -492,7 +503,7 @@ topology and update all the required fields.
 .. note:: Update all the required fields like ip, user, password, pcis, etc...
 
 SR-IOV Config pod_trex.yaml
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
++++++++++++++++++++++++++++
 
 .. code-block:: YAML
 
@@ -521,7 +532,7 @@ SR-IOV Config pod_trex.yaml
                 local_mac: "00:00.00:00:00:02"
 
 SR-IOV Config host_sriov.yaml
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
++++++++++++++++++++++++++++++
 
 .. code-block:: YAML
 
@@ -537,7 +548,7 @@ SR-IOV testcase update:
 ``<yardstick>/samples/vnf_samples/nsut/vfw/tc_sriov_rfc2544_ipv4_1rule_1flow_64B_trex.yaml``
 
 Update "contexts" section
-"""""""""""""""""""""""""
+'''''''''''''''''''''''''
 
 .. code-block:: YAML
 
@@ -582,10 +593,10 @@ Update "contexts" section
 
 
 OVS-DPDK
---------
+~~~~~~~~
 
 OVS-DPDK Pre-requisites
-^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~
 
 On Host, where VM is created:
  a) Create and configure a bridge named ``br-int`` for VM to connect to external network.
@@ -659,11 +670,10 @@ On Host, where VM is created:
 
 
 OVS-DPDK Config pod.yaml describing Topology
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+++++++++++++++++++++++++++++++++++++++++++++
 
 OVS-DPDK 2-Node setup
-^^^^^^^^^^^^^^^^^^^^^
-
++++++++++++++++++++++
 
 .. code-block:: console
 
@@ -693,7 +703,7 @@ OVS-DPDK 2-Node setup
 
 
 OVS-DPDK 3-Node setup - Correlated Traffic
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+++++++++++++++++++++++++++++++++++++++++++
 
 .. code-block:: console
 
@@ -733,7 +743,7 @@ topology and update all the required fields.
 .. note:: Update all the required fields like ip, user, password, pcis, etc...
 
 OVS-DPDK Config pod_trex.yaml
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
++++++++++++++++++++++++++++++
 
 .. code-block:: YAML
 
@@ -761,7 +771,7 @@ OVS-DPDK Config pod_trex.yaml
               local_mac: "00:00.00:00:00:02"
 
 OVS-DPDK Config host_ovs.yaml
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
++++++++++++++++++++++++++++++
 
 .. code-block:: YAML
 
@@ -777,7 +787,7 @@ ovs_dpdk testcase update:
 ``<yardstick>/samples/vnf_samples/nsut/vfw/tc_ovs_rfc2544_ipv4_1rule_1flow_64B_trex.yaml``
 
 Update "contexts" section
-"""""""""""""""""""""""""
+'''''''''''''''''''''''''
 
 .. code-block:: YAML
 
@@ -832,7 +842,7 @@ Update "contexts" section
 
 
 Network Service Benchmarking - OpenStack with SR-IOV support
-============================================================
+------------------------------------------------------------
 
 This section describes how to run a Sample VNF test case, using Heat context,
 with SR-IOV. It also covers how to install OpenStack in Ubuntu 16.04, using
@@ -840,7 +850,7 @@ DevStack, with SR-IOV support.
 
 
 Single node OpenStack setup with external TG
---------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: console
 
@@ -871,7 +881,7 @@ Single node OpenStack setup with external TG
 
 
 Host pre-configuration
-^^^^^^^^^^^^^^^^^^^^^^
+++++++++++++++++++++++
 
 .. warning:: The following configuration requires sudo access to the system. Make
   sure that your user have the access.
@@ -971,7 +981,7 @@ Setup SR-IOV ports on the host:
 
 
 DevStack installation
-^^^^^^^^^^^^^^^^^^^^^
++++++++++++++++++++++
 
 Use official `Devstack <https://docs.openstack.org/devstack/pike/>`_
 documentation to install OpenStack on a host. Please note, that stable
@@ -993,7 +1003,7 @@ Start the devstack installation on a host.
 
 
 TG host configuration
-^^^^^^^^^^^^^^^^^^^^^
++++++++++++++++++++++
 
 Yardstick automatically install and configure Trex traffic generator on TG
 host based on provided POD file (see below). Anyway, it's recommended to check
@@ -1002,7 +1012,7 @@ the manual at https://trex-tgn.cisco.com/trex/doc/trex_manual.html.
 
 
 Run the Sample VNF test case
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+++++++++++++++++++++++++++++
 
 There is an example of Sample VNF test case ready to be executed in an
 OpenStack environment with SR-IOV support: ``samples/vnf_samples/nsut/vfw/
@@ -1027,7 +1037,7 @@ context using steps described in `NS testing - using yardstick CLI`_ section.
 
 
 Multi node OpenStack TG and VNF setup (two nodes)
--------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: console
 
@@ -1058,14 +1068,14 @@ Multi node OpenStack TG and VNF setup (two nodes)
 
 
 Controller/Compute pre-configuration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+++++++++++++++++++++++++++++++++++++
 
 Pre-configuration of the controller and compute hosts are the same as
 described in `Host pre-configuration`_ section. Follow the steps in the section.
 
 
 DevStack configuration
-^^^^^^^^^^^^^^^^^^^^^^
+++++++++++++++++++++++
 
 Use official `Devstack <https://docs.openstack.org/devstack/pike/>`_
 documentation to install OpenStack on a host. Please note, that stable
@@ -1092,7 +1102,7 @@ Start the devstack installation on the controller and compute hosts.
 
 
 Run the sample vFW TC
-^^^^^^^^^^^^^^^^^^^^^
++++++++++++++++++++++
 
 Install yardstick using `Install Yardstick (NSB Testing)`_ steps for OpenStack
 context.
@@ -1109,10 +1119,10 @@ and the following yardtick command line arguments:
 
 
 Enabling other Traffic generator
-================================
+--------------------------------
 
 IxLoad
-^^^^^^
+~~~~~~
 
 1. Software needed: IxLoadAPI ``<IxLoadTclApi verson>Linux64.bin.tgz`` and
    ``<IxOS version>Linux64.bin.tar.gz`` (Download from ixia support site)
@@ -1153,7 +1163,7 @@ IxLoad
    ``<repo>/samples/vnf_samples/nsut/vfw/tc_baremetal_http_ixload_1b_Requests-65000_Concurrency.yaml``
 
 IxNetwork
----------
+~~~~~~~~~
 
 IxNetwork testcases use IxNetwork API Python Bindings module, which is
 installed as part of the requirements of the project.
diff --git a/docs/testing/user/userguide/opnfv_yardstick_tc087.rst b/docs/testing/user/userguide/opnfv_yardstick_tc087.rst
index 99bfeebfc..d3aed6b5b 100644
--- a/docs/testing/user/userguide/opnfv_yardstick_tc087.rst
+++ b/docs/testing/user/userguide/opnfv_yardstick_tc087.rst
@@ -10,7 +10,7 @@ Yardstick Test Case Description TC087
 +-----------------------------------------------------------------------------+
 |SDN Controller resilience in non-HA configuration                            |
 |                                                                             |
-+--------------+--------------------------------------------------------------+
++==============+==============================================================+
 |test case id  | OPNFV_YARDSTICK_TC087: SDN controller resilience in          |
 |              | non-HA configuration                                         |
 |              |                                                              |