CSIT-744 Update report content for proper parsing

Follow the good practices for formatting. Update the content of release
report RST files to use the proper directives like :cite:, :footnote:,
:abbr:, :captions: etc.With these markings we will be able to format
output in proper way and style it in various sphinx output builders.

Change-Id: Ibbb538d43c3bd364a6acdcc990097a477f49de00
Signed-off-by: Peter Mikus <pmikus@cisco.com>

3 files changed, 31 insertions, 29 deletions

diff --git a/docs/report/introduction/csit_design.rst b/docs/report/introduction/csit_design.rst
index 0674c50775..7798081a59 100644
--- a/docs/report/introduction/csit_design.rst
+++ b/docs/report/introduction/csit_design.rst
@@ -32,7 +32,7 @@ including CSIT framework is depicted in the figure below.
    :alt: FD.io CSIT system design

    :align: center

 

-   *Figure 1. FD.io CSIT system design*

+   *FD.io CSIT system design*

 

 A brief bottom-up description is provided here:

 

@@ -161,14 +161,15 @@ RF Keywords Naming Guidelines
 

 Readability counts: "..code is read much more often than it is written."

 Hence following a good and consistent grammar practice is important when

-writing RF KeyWords and Tests. All CSIT test cases are coded using

-Gherkin style and include only L2 KWs references. L2 KWs are coded using

-simple style and include L2 KWs, L1 KWs, and L1 python references. To

-improve readability, the proposal is to use the same grammar for both RF

-KW styles, and to formalize the grammar of English sentences used for

-naming the RF KWs. RF KWs names are short sentences expressing

-functional description of the command. They must follow English sentence

-grammar in one of the following forms:

+writing :abbr:`RF (Robot Framework)` KeyWords and Tests. All CSIT test cases

+are coded using Gherkin style and include only L2 KWs references. L2 KWs are

+coded using simple style and include L2 KWs, L1 KWs, and L1 python references.

+To improve readability, the proposal is to use the same grammar for both

+:abbr:`RF (Robot Framework)` KW styles, and to formalize the grammar of English

+sentences used for naming the :abbr:`RF (Robot Framework)` KWs. :abbr:`RF (Robot

+Framework)` KWs names are short sentences expressing functional description of

+the command. They must follow English sentence grammar in one of the following

+forms:

 

 #. **Imperative** - verb-object(s): *"Do something"*, verb in base form.

 #. **Declarative** - subject–verb–object(s): *"Subject does something"*, verb in

@@ -181,8 +182,8 @@ grammar in one of the following forms:
 Passive form MUST NOT be used. However a usage of past participle as an

 adjective is okay. See usage examples provided in the Coding guidelines

 section below. Following sections list applicability of the above

-grammar forms to different RF KW categories. Usage examples are

-provided, both good and bad.

+grammar forms to different :abbr:`RF (Robot Framework)` KW categories. Usage

+examples are provided, both good and bad.

 

 Coding guidelines

 -----------------

diff --git a/docs/report/introduction/general_notes.rst b/docs/report/introduction/general_notes.rst
index 380f109764..50a9d4c4a3 100644
--- a/docs/report/introduction/general_notes.rst
+++ b/docs/report/introduction/general_notes.rst
@@ -2,13 +2,14 @@ General Notes
 =============
 
 All CSIT test results listed in this report are sourced and auto-generated
-from output.xml Robot Framework (RF) files resulting from LF FD.io Jenkins
-jobs execution against |vpp-release| release artifacts. References are
-provided to the original LF FD.io Jenkins job results. However, as LF FD.io
-Jenkins infrastructure does not automatically archive all jobs (history record
-is provided for the last 30 days or 40 jobs only), additional references are
-provided to the RF result files that got archived in FD.io nexus online
-storage system.
+from :file:`output.xml` :abbr:`RF (Robot Framework)` files resulting from
+:abbr:`LF (Linux Foundation)` FD.io Jenkins jobs execution against |vpp-release|
+release artifacts. References are provided to the original :abbr:`LF (Linux
+Foundation)` FD.io Jenkins job results. However, as :abbr:`LF (Linux
+Foundation)` FD.io Jenkins infrastructure does not automatically archive all jobs
+(history record is provided for the last 30 days or 40 jobs only), additional
+references are provided to the :abbr:`RF (Robot Framework)` result files that
+got archived in FD.io nexus online storage system.
 
 FD.io CSIT project currently covers multiple FD.io system and sub-system
 testing areas and this is  reflected in this report, where each testing area
@@ -42,9 +43,9 @@ is listed separately, as follows:
    against VPP.
 
 #. **Honeycomb Performance Tests** - Honeycomb performance tests are executed in
-   physical FD.io testbeds, focusing on the performance of Honeycomb management and programming
-   functionality of VPP. Tests cover a range of CRUD operations executed
-   against VPP.
+   physical FD.io testbeds, focusing on the performance of Honeycomb management
+   and programming functionality of VPP. Tests cover a range of CRUD operations
+   executed against VPP.
 
 #. **NSH_SFC Functional Tests** - NSH_SFC functional tests are executed in
    virtual FD.io testbeds focusing on NSH_SFC of VPP. Tests cover a range of
@@ -56,12 +57,12 @@ complement CSIT system functional tests, they are provided mainly as a reference
 and to provide a more complete view of automated testing executed against
 |vpp-release|.
 
-FD.io CSIT system is developed using two main coding platforms: Robot
-Framework (RF) and Python. CSIT |release| source code for the executed test
+FD.io CSIT system is developed using two main coding platforms :abbr:`RF (Robot
+Framework)` and Python. CSIT |release| source code for the executed test
 suites is available in CSIT branch |release| in the directory
-"./tests/<name_of_the_test_suite>". A local copy of CSIT source code can be
-obtained by cloning CSIT git repository - "git clone
-https://gerrit.fd.io/r/csit". The CSIT testing virtual environment can be run
+:file:`./tests/<name_of_the_test_suite>`. A local copy of CSIT source code
+can be obtained by cloning CSIT git repository - :command:`git clone
+https://gerrit.fd.io/r/csit`. The CSIT testing virtual environment can be run
 on a local computer workstation (laptop, server) using Vagrant by following
 the instructions in `CSIT tutorials
 <https://wiki.fd.io/view/CSIT#Tutorials>`_.
diff --git a/docs/report/introduction/overview.rst b/docs/report/introduction/overview.rst
index 57b4cd4897..180e73ff57 100644
--- a/docs/report/introduction/overview.rst
+++ b/docs/report/introduction/overview.rst
@@ -7,9 +7,9 @@ This is the **F**\ast **D**\ata **I**/**O** Project (**FD.io**) **C**\ontinuous
 
 The report describes CSIT functional and performance tests and their
 continuous execution delivered in CSIT |release|. A high-level overview is
-provided for each CSIT test environment running in Linux Foundation (LF) FD.io
-Continuous Performance Labs. This is followed by summary of all executed tests
-against the |vpp-release| and associated FD.io projects and sub-systems
+provided for each CSIT test environment running in :abbr:`LF (Linux Foundation)`
+FD.io Continuous Performance Labs. This is followed by summary of all executed
+tests against the |vpp-release| and associated FD.io projects and sub-systems
 (Honeycomb, DPDK, NSH_SFC), CSIT |release| release notes, result highlights and
 known issues discovered in CSIT. More detailed description of each environment,
 pointers to CSIT test code documentation and detailed test resuls with links to