Fix Functest Config Guide

It allows building this documentation via tox.
rst files are now checked via doc8.

Intro is moved into a new file.

Change-Id: Ic5c0108cf1cbb0fc69f7e2cc73cf2fb69e44baa1
Signed-off-by: Cédric Ollivier <cedric.ollivier@orange.com>

6 files changed, 310 insertions, 115 deletions

diff --git a/docs/testing/user/configguide/ci.rst b/docs/testing/user/configguide/ci.rst
index f3901d867..e4fec51dc 100644
--- a/docs/testing/user/configguide/ci.rst
+++ b/docs/testing/user/configguide/ci.rst
@@ -1,3 +1,5 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
 Integration in CI
 =================
 In CI we use the Docker images and execute the appropriate commands within the
@@ -5,7 +7,8 @@ container from Jenkins.
 
 4 steps have been defined::
   * functest-cleanup: clean existing functest dockers on the jumphost
-  * functest-daily: run dockers opnfv/functest-* (healthcheck, smoke, features, vnf)
+  * functest-daily: run dockers opnfv/functest-* (healthcheck, smoke, features,
+    vnf)
   * functest-store-results: push logs to artifacts
 
 See `[3]`_ for details.
diff --git a/docs/testing/user/configguide/conf.py b/docs/testing/user/configguide/conf.py
new file mode 100644
index 000000000..a227d7caa
--- /dev/null
+++ b/docs/testing/user/configguide/conf.py
@@ -0,0 +1,185 @@
+# -*- coding: utf-8 -*-
+#
+# Functest Installation Guide documentation build configuration file, created
+# by sphinx-quickstart on Tue Apr  3 03:51:57 2018.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+import sphinx_opnfv_theme
+
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Functest Installation Guide'
+copyright = u'2018, Cédric Ollivier <cedric.ollivier@orange.com>'
+author = u'Cédric Ollivier <cedric.ollivier@orange.com>'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'master'
+# The full version, including alpha/beta/rc tags.
+release = u'master'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'opnfv'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+html_theme_options = {
+    'bootswatch_theme': 'journal',
+    'navbar_sidebarrel': False,
+    'navbar_title': '',
+}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = []
+html_theme_path = sphinx_opnfv_theme.get_html_theme_path()
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = []
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    '**': [
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+    ]
+}
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'FunctestInstallationGuidedoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc,
+     'FunctestInstallationGuide.tex',
+     u'Functest Installation Guide Documentation',
+     u'Cédric Ollivier \\textless{}cedric.ollivier@orange.com\\textgreater{}',
+     'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc,
+     'functestinstallationguide',
+     u'Functest Installation Guide Documentation',
+     [author],
+     1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc,
+     'FunctestInstallationGuide',
+     u'Functest Installation Guide Documentation',
+     author,
+     'FunctestInstallationGuide',
+     'One line description of project.',
+     'Miscellaneous'),
+]
diff --git a/docs/testing/user/configguide/configguide.rst b/docs/testing/user/configguide/configguide.rst
index ef40bf598..a29ff3aaa 100644
--- a/docs/testing/user/configguide/configguide.rst
+++ b/docs/testing/user/configguide/configguide.rst
@@ -1,4 +1,3 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. SPDX-License-Identifier: CC-BY-4.0
 
 Installation and configuration
@@ -23,8 +22,9 @@ Docker images are available on the dockerhub:
   * opnfv/functest-parser
   * opnfv/functest-restapi
 
-The tag "opnfv-5.0.0" is the official release image in Euphrates, but you can also pull "euphrates"
-tag as it is being maintained by Functest team and might include bugfixes.
+The tag "opnfv-5.0.0" is the official release image in Euphrates, but you can
+also pull "euphrates" tag as it is being maintained by Functest team and might
+include bugfixes.
 
 The Functest docker container environment can -in principle- be also
 used with non-OPNFV official installers (e.g. 'devstack'), with the
@@ -173,10 +173,10 @@ Testing vnf suite
 
 Run vnf suite::
 
-sudo docker run --env-file env \
-    -v $(pwd)/openstack.creds:/home/opnfv/functest/conf/env_file \
-    -v $(pwd)/images:/home/opnfv/functest/images \
-    opnfv/functest-vnf
+  sudo docker run --env-file env \
+      -v $(pwd)/openstack.creds:/home/opnfv/functest/conf/env_file \
+      -v $(pwd)/images:/home/opnfv/functest/images \
+      opnfv/functest-vnf
 
 Results shall be displayed as follows::
 
@@ -218,8 +218,8 @@ release note.
 
 **NOTE:** The scenario name is mainly used to automatically detect
 if a test suite is runnable or not (e.g. it will prevent ODL test suite to be
-run on 'nosdn' scenarios). If not set, Functest will try to run the default test
-cases that might not include SDN controller or a specific feature
+run on 'nosdn' scenarios). If not set, Functest will try to run the default
+test cases that might not include SDN controller or a specific feature.
 
 **NOTE:** An HA scenario means that 3 OpenStack controller nodes are
 deployed. It does not necessarily mean that the whole system is HA. See
@@ -478,6 +478,7 @@ We may distinguish several directories, the first level has 5 directories:
 
 Functest directory has 7 sub-directories, which is located under
 /usr/lib/python2.7/site-packages/functest:
+
   * **api**: This directory is dedicated for the internal Functest API.
   * **ci**: This directory contains test structure definition files
     (e.g <filename>.yaml) and bash shell/python scripts used to
@@ -605,6 +606,8 @@ If the OpenStack command still does not show anything or complains
 about connectivity issues, it could be due to an incorrect url given to
 the OS_AUTH_URL environment variable. Check the deployment settings.
 
+.. _`Proxy support`:
+
 Proxy support
 -------------
 If your Jumphost node is operating behind a http proxy, then there are
@@ -614,7 +617,7 @@ succeed:
   #. Initial installation of docker engine First, try following the
      official Docker documentation for Proxy settings. Some issues were
      experienced on CentOS 7 based Jumphost. Some tips are documented
-     in section: `Docker Installation on CentOS behind http proxy`_
+     in section: :ref:`Docker Installation on CentOS behind http proxy`
      below.
 
 If that is the case, make sure the resolv.conf and the needed
@@ -677,6 +680,8 @@ commands might not work. You can use the **curl** command instead.
   (Ignore the content. If command returns a valid HTML page, it proves
   the connection.)
 
+.. _`Docker Installation on CentOS behind http proxy`:
+
 Docker Installation on CentOS behind http proxy
 -----------------------------------------------
 This section is applicable for CentOS family OS on Jumphost which
diff --git a/docs/testing/user/configguide/index.rst b/docs/testing/user/configguide/index.rst
index fd997344b..5d7eeb6e4 100644
--- a/docs/testing/user/configguide/index.rst
+++ b/docs/testing/user/configguide/index.rst
@@ -1,5 +1,4 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
+.. SPDX-License-Identifier: CC-BY-4.0
 
 ***************************
 Functest Installation Guide
@@ -9,101 +8,10 @@ Functest Installation Guide
    :numbered:
    :maxdepth: 2
 
-
-Introduction
-============
-This document describes how to install and configure Functest in OPNFV.
-
-High level architecture
------------------------
-
-The high level architecture of Functest within OPNFV can be described as
-follows::
-
- CIMC/Lights+out management               Admin  Mgmt/API  Public  Storage Private
-                                           PXE
- +                                           +       +        +       +       +
- |                                           |       |        |       |       |
- |     +----------------------------+        |       |        |       |       |
- |     |                            |        |       |        |       |       |
- +-----+       Jumphost             |        |       |        |       |       |
- |     |                            |        |       |        |       |       |
- |     |   +--------------------+   |        |       |        |       |       |
- |     |   |                    |   |        |       |        |       |       |
- |     |   | Tools              |   +----------------+        |       |       |
- |     |   | - Rally            |   |        |       |        |       |       |
- |     |   | - Robot            |   |        |       |        |       |       |
- |     |   | - RefStack         |   |        |       |        |       |       |
- |     |   |                    |   |-------------------------+       |       |
- |     |   | Testcases          |   |        |       |        |       |       |
- |     |   | - VIM              |   |        |       |        |       |       |
- |     |   |                    |   |        |       |        |       |       |
- |     |   | - SDN Controller   |   |        |       |        |       |       |
- |     |   |                    |   |        |       |        |       |       |
- |     |   | - Features         |   |        |       |        |       |       |
- |     |   |                    |   |        |       |        |       |       |
- |     |   | - VNF              |   |        |       |        |       |       |
- |     |   |                    |   |        |       |        |       |       |
- |     |   +--------------------+   |        |       |        |       |       |
- |     |     Functest Docker        +        |       |        |       |       |
- |     |                            |        |       |        |       |       |
- |     |                            |        |       |        |       |       |
- |     |                            |        |       |        |       |       |
- |     +----------------------------+        |       |        |       |       |
- |                                           |       |        |       |       |
- |    +----------------+                     |       |        |       |       |
- |    |             1  |                     |       |        |       |       |
- +----+ +--------------+-+                   |       |        |       |       |
- |    | |             2  |                   |       |        |       |       |
- |    | | +--------------+-+                 |       |        |       |       |
- |    | | |             3  |                 |       |        |       |       |
- |    | | | +--------------+-+               |       |        |       |       |
- |    | | | |             4  |               |       |        |       |       |
- |    +-+ | | +--------------+-+             |       |        |       |       |
- |      | | | |             5  +-------------+       |        |       |       |
- |      +-+ | |  nodes for     |             |       |        |       |       |
- |        | | |  deploying     +---------------------+        |       |       |
- |        +-+ |  OPNFV         |             |       |        |       |       |
- |          | |                +------------------------------+       |       |
- |          +-+     SUT        |             |       |        |       |       |
- |            |                +--------------------------------------+       |
- |            |                |             |       |        |       |       |
- |            |                +----------------------------------------------+
- |            +----------------+             |       |        |       |       |
- |                                           |       |        |       |       |
- +                                           +       +        +       +       +
-              SUT = System Under Test
-
-Note connectivity to management network is not needed for most of the testcases.
-But it may be needed for some specific snaps tests.
-
-All the libraries and dependencies needed by all of the Functest tools are
-pre-installed into the Docker images. This allows running Functest on any
-platform.
-
-The automated mechanisms inside the Functest Docker containers will:
-
-  * Prepare the environment according to the System Under Test (SUT)
-  * Perform the appropriate functional tests
-  * Push the test results into the OPNFV test result database (optional)
-
-The OpenStack credentials file must be provided to the container.
-
-These Docker images can be integrated into CI or deployed independently.
-
-Please note that the Functest Docker images have been designed for OPNFV,
-however, it would be possible to adapt them to any OpenStack based VIM +
-controller environment, since most of the test cases are integrated from
-upstream communities.
-
-The functional test cases are described in the Functest User Guide `[2]`_
-
-.. include:: ./prerequisites.rst
-
-.. include:: ./configguide.rst
-
-.. include:: ./ci.rst
-
+   intro.rst
+   prerequisites.rst
+   configguide.rst
+   ci.rst
 
 References
 ==========
diff --git a/docs/testing/user/configguide/intro.rst b/docs/testing/user/configguide/intro.rst
new file mode 100644
index 000000000..72730b253
--- /dev/null
+++ b/docs/testing/user/configguide/intro.rst
@@ -0,0 +1,91 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Introduction
+============
+This document describes how to install and configure Functest in OPNFV.
+
+High level architecture
+-----------------------
+
+The high level architecture of Functest within OPNFV can be described as
+follows::
+
+ CIMC/Lights+out management               Admin  Mgmt/API  Public  Storage Private
+                                           PXE
+ +                                           +       +        +       +       +
+ |                                           |       |        |       |       |
+ |     +----------------------------+        |       |        |       |       |
+ |     |                            |        |       |        |       |       |
+ +-----+       Jumphost             |        |       |        |       |       |
+ |     |                            |        |       |        |       |       |
+ |     |   +--------------------+   |        |       |        |       |       |
+ |     |   |                    |   |        |       |        |       |       |
+ |     |   | Tools              |   +----------------+        |       |       |
+ |     |   | - Rally            |   |        |       |        |       |       |
+ |     |   | - Robot            |   |        |       |        |       |       |
+ |     |   | - RefStack         |   |        |       |        |       |       |
+ |     |   |                    |   |-------------------------+       |       |
+ |     |   | Testcases          |   |        |       |        |       |       |
+ |     |   | - VIM              |   |        |       |        |       |       |
+ |     |   |                    |   |        |       |        |       |       |
+ |     |   | - SDN Controller   |   |        |       |        |       |       |
+ |     |   |                    |   |        |       |        |       |       |
+ |     |   | - Features         |   |        |       |        |       |       |
+ |     |   |                    |   |        |       |        |       |       |
+ |     |   | - VNF              |   |        |       |        |       |       |
+ |     |   |                    |   |        |       |        |       |       |
+ |     |   +--------------------+   |        |       |        |       |       |
+ |     |     Functest Docker        +        |       |        |       |       |
+ |     |                            |        |       |        |       |       |
+ |     |                            |        |       |        |       |       |
+ |     |                            |        |       |        |       |       |
+ |     +----------------------------+        |       |        |       |       |
+ |                                           |       |        |       |       |
+ |    +----------------+                     |       |        |       |       |
+ |    |             1  |                     |       |        |       |       |
+ +----+ +--------------+-+                   |       |        |       |       |
+ |    | |             2  |                   |       |        |       |       |
+ |    | | +--------------+-+                 |       |        |       |       |
+ |    | | |             3  |                 |       |        |       |       |
+ |    | | | +--------------+-+               |       |        |       |       |
+ |    | | | |             4  |               |       |        |       |       |
+ |    +-+ | | +--------------+-+             |       |        |       |       |
+ |      | | | |             5  +-------------+       |        |       |       |
+ |      +-+ | |  nodes for     |             |       |        |       |       |
+ |        | | |  deploying     +---------------------+        |       |       |
+ |        +-+ |  OPNFV         |             |       |        |       |       |
+ |          | |                +------------------------------+       |       |
+ |          +-+     SUT        |             |       |        |       |       |
+ |            |                +--------------------------------------+       |
+ |            |                |             |       |        |       |       |
+ |            |                +----------------------------------------------+
+ |            +----------------+             |       |        |       |       |
+ |                                           |       |        |       |       |
+ +                                           +       +        +       +       +
+              SUT = System Under Test
+
+Note connectivity to management network is not needed for most of the
+testcases. But it may be needed for some specific snaps tests.
+
+All the libraries and dependencies needed by all of the Functest tools are
+pre-installed into the Docker images. This allows running Functest on any
+platform.
+
+The automated mechanisms inside the Functest Docker containers will:
+
+  * Prepare the environment according to the System Under Test (SUT)
+  * Perform the appropriate functional tests
+  * Push the test results into the OPNFV test result database (optional)
+
+The OpenStack credentials file must be provided to the container.
+
+These Docker images can be integrated into CI or deployed independently.
+
+Please note that the Functest Docker images have been designed for OPNFV,
+however, it would be possible to adapt them to any OpenStack based VIM +
+controller environment, since most of the test cases are integrated from
+upstream communities.
+
+The functional test cases are described in the Functest User `[2]`_
+
+.. _`[2]`: http://docs.opnfv.org/en/latest/submodules/functest/docs/testing/user/userguide/index.html
diff --git a/docs/testing/user/configguide/prerequisites.rst b/docs/testing/user/configguide/prerequisites.rst
index 8289803bb..60be1b93b 100644
--- a/docs/testing/user/configguide/prerequisites.rst
+++ b/docs/testing/user/configguide/prerequisites.rst
@@ -1,3 +1,5 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
 Prerequisites
 =============
 The OPNFV deployment is out of the scope of this document but it can be
@@ -13,10 +15,11 @@ Several prerequisites are needed for Functest:
     #. Connectivity from the Jumphost to the SUT public/external network
 
 Some specific SNAPS tests may require a connectivity from the Jumphost to the
-SUT admin/management network but most of the test cases do not. This requirement
-can be changed by overriding the 'interface' attribute (OS_INTERFACE) value
-to 'public' in the credentials file. Another means to circumvent this issue
-would be to change the 'snaps.use_keystone' value from True to False.
+SUT admin/management network but most of the test cases do not. This
+requirement can be changed by overriding the 'interface' attribute
+(OS_INTERFACE) value to 'public' in the credentials file. Another means to
+circumvent this issue would be to change the 'snaps.use_keystone' value from
+True to False.
 
 WARNING: Connectivity from Jumphost is essential and it is of paramount
 importance to make sure it is working before even considering to install
@@ -29,7 +32,7 @@ deployment has been triggered previously, but it could be any server
 with proper connectivity to the SUT.
 
 NOTE: If your Jumphost is operating behind a company http proxy and/or
-firewall, please consult first the section `Proxy Support`_, towards
+firewall, please consult first the section :ref:`Proxy support`, towards
 the end of this document. The section details some tips/tricks which
 *may* be of help in a proxified environment.
 
@@ -44,8 +47,8 @@ commands below are offered as a short reference.
 
 *Tip:* For running docker containers behind the proxy, you need first
 some extra configuration which is described in section
-`Docker Installation on CentOS behind http proxy`_. You should follow
-that section before installing the docker engine.
+:ref:`Docker Installation on CentOS behind http proxy`. You should follow that
+section before installing the docker engine.
 
 Docker installation needs to be done as root user. You may use other
 userid's to create and run the actual containers later if so desired.