Formatting changes and fixing of build warnings

Applying a different sphinx rendering theme to make the document
more readable (in my opinion). The Sphinx config file is based on
the config file of the Copper project. Moreover, this change
fixes a few build-time warnings.

Change-Id: I78f5268436edcfa8c71b8e85a99c7caa54a0e099
Signed-off-by: Georg Kunz <georg.kunz@ericsson.com>
(cherry picked from commit 12542964182af4da4daeb58219377a5d1f697ecf)

9 files changed, 125 insertions, 67 deletions

diff --git a/docs/requirements/conf.py b/docs/requirements/conf.py
new file mode 100644
index 0000000..9912324
--- /dev/null
+++ b/docs/requirements/conf.py
@@ -0,0 +1,55 @@
+# Copyright 2016 Open Platform for NFV Project, Inc. and its contributors
+#  
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#  
+# http://www.apache.org/licenses/LICENSE-2.0
+#  
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# What this is: Configuration file for OPNFV NetReady requirements
+# documentation based on the configuration file used by the Copper project.
+#
+
+import datetime
+import sys
+import os
+import subprocess
+
+try:
+    __import__('imp').find_module('sphinx.ext.numfig')
+    extensions = ['sphinx.ext.numfig']
+except ImportError:
+    # 'pip install sphinx_numfig'
+    extensions = ['sphinx_numfig']
+
+try:
+    __import__('imp').find_module('sphinxcontrib-fulltoc')
+except ImportError:
+    subprocess.call("pip install sphinxcontrib-fulltoc", shell=True)
+extensions.append('sphinxcontrib-fulltoc')
+
+# numfig:
+number_figures = True
+figure_caption_prefix = "Fig."
+
+source_suffix = '.rst'
+master_doc = 'index'
+pygments_style = 'sphinx'
+html_use_index = True
+html_theme = 'sphinx_rtd_theme'
+
+pdf_documents = [('index', u'OPNFV', u'OPNFV NetReady Project', u'OPNFV')]
+pdf_fit_mode = "shrink"
+pdf_stylesheets = ['sphinx','kerning','a4']
+#latex_domain_indices = False
+#latex_use_modindex = False
+
+latex_elements = {
+    'printindex': '',
+}
diff --git a/docs/requirements/glossary.rst b/docs/requirements/glossary.rst
index fb7f7e7..f6d55cd 100644
--- a/docs/requirements/glossary.rst
+++ b/docs/requirements/glossary.rst
@@ -1,7 +1,8 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
-**Definition of terms**
+Definition of terms
+===================
 
 Different standards developing organizations and communities use different
 terminology related to Network Function Virtualization, Cloud Computing, and
diff --git a/docs/requirements/index.rst b/docs/requirements/index.rst
index 21147bd..6c4516f 100644
--- a/docs/requirements/index.rst
+++ b/docs/requirements/index.rst
@@ -41,9 +41,6 @@ NetReady: Network Readiness
 
     \newpage
 
-.. include::
-    glossary.rst
-
 .. toctree::
     :maxdepth: 4
     :numbered:
@@ -52,4 +49,5 @@ NetReady: Network Readiness
     use_cases.rst
     retired_use_cases.rst
     summary.rst
+    glossary.rst
     references.rst
diff --git a/docs/requirements/references.rst b/docs/requirements/references.rst
index 5f1f925..76cb5bf 100644
--- a/docs/requirements/references.rst
+++ b/docs/requirements/references.rst
@@ -1,8 +1,8 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
-.. References
-.. ==========
+References
+==========
 
 .. [BGPVPN] http://docs.openstack.org/developer/networking-bgpvpn/
 .. [MULTISITE] https://wiki.opnfv.org/display/multisite/Multisite
diff --git a/docs/requirements/use_cases/georedundancy_cells.rst b/docs/requirements/use_cases/georedundancy_cells.rst
index e1673a6..a4d1f0c 100644
--- a/docs/requirements/use_cases/georedundancy_cells.rst
+++ b/docs/requirements/use_cases/georedundancy_cells.rst
@@ -46,7 +46,7 @@ Dependencies on compute services
 Data model objects
 ++++++++++++++++++
    - local and remote endpoint objects (Most probably IP addresses with some
-   additional properties).
+     additional properties).
 
 Current implementation
 ~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/requirements/use_cases/georedundancy_regions_insances.rst b/docs/requirements/use_cases/georedundancy_regions_insances.rst
index e3faf2d..c2550eb 100644
--- a/docs/requirements/use_cases/georedundancy_regions_insances.rst
+++ b/docs/requirements/use_cases/georedundancy_regions_insances.rst
@@ -39,7 +39,7 @@ Northbound API / Workflow
 Data model objects
 ++++++++++++++++++
 - local and remote endpoint objects (Most probably IP addresses with some
-additional properties).
+  additional properties).
 
 Current implementation
 ~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/requirements/use_cases/l3vpn_ecmp.rst b/docs/requirements/use_cases/l3vpn_ecmp.rst
index 7bcb64f..93f5234 100644
--- a/docs/requirements/use_cases/l3vpn_ecmp.rst
+++ b/docs/requirements/use_cases/l3vpn_ecmp.rst
@@ -135,14 +135,14 @@ Gaps in the current solution
 Given the use case description and the currently available implementation in
 OpenStack provided by BGPVPN project, we identify the following gaps:
 
-* [L3VPN-ECMP-GAP1] Static routes are not yet supported by the BGPVPN project.
+* **[L3VPN-ECMP-GAP1] Static routes are not yet supported by the BGPVPN project.**
 
   Currently, no API for configuring static routes is available in the BGPVPN
   project. This feature is on the road map, however.
 
 
-* [L3VPN-ECMP-GAP2] Behavior not defined for multiple Neutron ports of the same
-  IP
+* **[L3VPN-ECMP-GAP2] Behavior not defined for multiple Neutron ports of the same
+  IP**
 
   The Neutron and BGPVPN API allow for creating multiple ports with the same
   IP in different networks and associating the networks with the same VPN. The
@@ -151,8 +151,8 @@ OpenStack provided by BGPVPN project, we identify the following gaps:
   of this feature is on the road map of the project, however.
 
 
-* [L3VPN-ECMP-GAP3] It is not possible to assign the same IP to multiple Neutron
-  ports within the same Neutron subnet.
+* **[L3VPN-ECMP-GAP3] It is not possible to assign the same IP to multiple Neutron
+  ports within the same Neutron subnet.**
 
   This is due to the fundamental requirement of avoiding IP collisions within
   the L2 domain which is a Neutron network.
diff --git a/docs/requirements/use_cases/l3vpn_hub_and_spoke.rst b/docs/requirements/use_cases/l3vpn_hub_and_spoke.rst
index ca58f67..e98bd25 100644
--- a/docs/requirements/use_cases/l3vpn_hub_and_spoke.rst
+++ b/docs/requirements/use_cases/l3vpn_hub_and_spoke.rst
@@ -108,20 +108,24 @@ by creating a dedicated Neutron network with two subnets for each VRF in the
 Hub-and-Spoke topology.
 
 1. Create Neutron network "hub"
+
   ``neutron net-create --tenant-id Blue hub``
 
 
 2. Create a separate Neutron network for every "spoke"
+
   ``neutron net-create --tenant-id Blue spoke-i``
 
 
 3. For every network (hub and spokes), create two subnets
+
   ``neutron subnet-create <hub/spoke-i UUID> --tenant-id Blue 10.1.1.0/24``
 
   ``neutron subnet-create <hub/spoke-i UUID> --tenant-id Blue 10.3.7.0/24``
 
 
 4. Create the Neutron ports in the corresponding networks
+
   ``neutron port-create --tenant-id Blue --name vFW(H) --fixed-ip subnet_id=<hub UUID>,ip_address=10.1.1.5``
 
   ``neutron port-create --tenant-id Blue --name VNF1(S) --fixed-ip subnet_id=<spoke-i UUID>,ip_address=10.3.7.9``
@@ -133,19 +137,23 @@ Hub-and-Spoke topology.
 
 5. Create a BGPVPN object (VRF) for the hub network with the corresponding import
    and export targets
+
   ``neutron bgpvpn-create --name hub-vrf --import-targets <RT-hub RT-spoke> --export-targets <RT-hub>``
 
 
 6. Create a BGPVPN object (VRF) for every spoke network with the corresponding import
    and export targets
+
   ``neutron bgpvpn-create --name spoke-i-vrf --import-targets <RT-hub> --export-targets <RT-spoke>``
 
 
 7. Associate the hub network with the hub VRF
+
   ``bgpvpn-net-assoc-create hub --network <hub network-UUID>``
 
 
 8. Associate each spoke network with the corresponding spoke VRF
+
   ``bgpvpn-net-assoc-create spoke-i --network <spoke-i network-UUID>``
 
 
@@ -191,64 +199,61 @@ OpenStack provided by [BGPVPN]_ project and [NETWORKING-SFC]_ project,
 we identify the following gaps:
 
 
-[L3VPN-HS-GAP1] No means to disable layer 2 semantic of Neutron networks
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+* **[L3VPN-HS-GAP1] No means to disable layer 2 semantic of Neutron networks**
 
-Neutron networks were originally designed to represent layer 2 broadcast
-domains. As such, all ports connected to a network are in principle
-inter-connected on layer 2 (not considering security rules here). In contrast,
-in order to realize L3VPN use cases such as the hub-and-spoke topology,
-connectivity among ports must be controllable on a per port basis on layer 3.
+  Neutron networks were originally designed to represent layer 2 broadcast
+  domains. As such, all ports connected to a network are in principle
+  inter-connected on layer 2 (not considering security rules here). In contrast,
+  in order to realize L3VPN use cases such as the hub-and-spoke topology,
+  connectivity among ports must be controllable on a per port basis on layer 3.
 
-There are ongoing efforts to relax this design assumption, for instance by means
-of routed networks ([NEUTRON-ROUTED-NETWORKS]_). In a routed network, a Neutron network
-is a layer 3 domain which is composed of multiple layer 2 segments. A routed
-network only provides layer 3 connectivity across segments, but layer 2
-connectivity across segments is **optional**. This means, depending on the
-particular networking backend and segmentation technique used, there might be
-layer 2 connectivity across segments or not. A new flag ``l2_adjacency``
-indicates whether or not a user can expect layer 2 connectivity or not across
-segments.
+  There are ongoing efforts to relax this design assumption, for instance by means
+  of routed networks ([NEUTRON-ROUTED-NETWORKS]_). In a routed network, a Neutron network
+  is a layer 3 domain which is composed of multiple layer 2 segments. A routed
+  network only provides layer 3 connectivity across segments, but layer 2
+  connectivity across segments is **optional**. This means, depending on the
+  particular networking backend and segmentation technique used, there might be
+  layer 2 connectivity across segments or not. A new flag ``l2_adjacency``
+  indicates whether or not a user can expect layer 2 connectivity or not across
+  segments.
 
-This flag, however, is ready-only and cannot be used to overwrite or disable the
-layer 2 semantics of a Neutron network.
+  This flag, however, is ready-only and cannot be used to overwrite or disable the
+  layer 2 semantics of a Neutron network.
 
 
-[L3VPN-HS-GAP2] No port-association available in the BGPVPN project yet
-'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+* **[L3VPN-HS-GAP2] No port-association available in the BGPVPN project yet**
 
-Due to gap [L3VPN-HS-GAP1], the [BGPVPN]_ project was not yet able to implement
-the concept of a port association. A port association would allow to associate
-individual ports with VRFs and thereby control layer 3 connectivity on a per
-port basis.
+  Due to gap [L3VPN-HS-GAP1], the [BGPVPN]_ project was not yet able to implement
+  the concept of a port association. A port association would allow to associate
+  individual ports with VRFs and thereby control layer 3 connectivity on a per
+  port basis.
 
-The workflow described above intents to mimic port associations by means of
-separate Neutron networks. Hence, the resulting workflow is overly complicated
-and not intuitive by requiring to create additional Neutron entities (networks)
-which are not present in the target topology. Moreover, creating large numbers
-of Neutron networks limits scalability.
+  The workflow described above intents to mimic port associations by means of
+  separate Neutron networks. Hence, the resulting workflow is overly complicated
+  and not intuitive by requiring to create additional Neutron entities (networks)
+  which are not present in the target topology. Moreover, creating large numbers
+  of Neutron networks limits scalability.
 
-Port associations are on the road map of the [BGPVPN]_ project, however, no
-design that overcomes the problems outlined above has been specified yet.
-Consequently, the time-line for this feature is unknown.
+  Port associations are on the road map of the [BGPVPN]_ project, however, no
+  design that overcomes the problems outlined above has been specified yet.
+  Consequently, the time-line for this feature is unknown.
 
-As a result, creating a clean Hub-and-Spoke topology is current not yet
-supported by the [BGPVPN]_ API.
+  As a result, creating a clean Hub-and-Spoke topology is current not yet
+  supported by the [BGPVPN]_ API.
 
 
-[L3VPN-HS-GAP3] No support for static routes in the BGPVPN project yet
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+* **[L3VPN-HS-GAP3] No support for static routes in the BGPVPN project yet**
 
-In order to realize the hub-and-spoke use case, a static route is needed to
-attract the traffic at the hub to the corresponding VNF (direct traffic to the
-firewall). Support for static routes in the BGPVPN project is available for the
-router association by means of the Neutron router extra routes feature. However,
-there is no support for static routes for network and port associations yet.
+  In order to realize the hub-and-spoke use case, a static route is needed to
+  attract the traffic at the hub to the corresponding VNF (direct traffic to the
+  firewall). Support for static routes in the BGPVPN project is available for the
+  router association by means of the Neutron router extra routes feature. However,
+  there is no support for static routes for network and port associations yet.
 
-Design work for supporting static routes for network associations has started,
-but no final design has been proposed yet.
+  Design work for supporting static routes for network associations has started,
+  but no final design has been proposed yet.
 
 ..
-.. [L3VPN-HS-GAP4] Creating a clean hub-and-spoke topology is current not yet supported by the NETWORKING-SFC API.
+.. L3VPN-HS-GAP4 Creating a clean hub-and-spoke topology is current not yet supported by the NETWORKING-SFC API.
 .. [Georg: We need to look deeper into SFC before we can substantiate our claim]
-
+..
diff --git a/docs/requirements/use_cases/multiple_backends.rst b/docs/requirements/use_cases/multiple_backends.rst
index 2aefe8a..a31d1ab 100644
--- a/docs/requirements/use_cases/multiple_backends.rst
+++ b/docs/requirements/use_cases/multiple_backends.rst
@@ -117,17 +117,16 @@ Given the use case description and the current implementation of OpenStack
 Neutron, we identify the following gaps:
 
 
-[MB-GAP1] Limited support for multiple back-ends
-'''''''''''''''''''''''''''''''''''''''''''''''
+* **[MB-GAP1] Limited support for multiple back-ends**
 
-As pointed out above, the Neutron core plugin mechanism only allows for one
-active plugin at a time. The ML2 plugin allows for running multiple mechanism
-drivers in parallel, however, successful inter-working strongly depends on the
-individual driver.
+  As pointed out above, the Neutron core plugin mechanism only allows for one
+  active plugin at a time. The ML2 plugin allows for running multiple mechanism
+  drivers in parallel, however, successful inter-working strongly depends on the
+  individual driver.
 
-Moreover, the ML2 plugin and its API is - by design - very layer 2 focused. For
-NFV networking use cases beyond layer 2, for instance L3VPNs, a more flexible
-API is required.
+  Moreover, the ML2 plugin and its API is - by design - very layer 2 focused. For
+  NFV networking use cases beyond layer 2, for instance L3VPNs, a more flexible
+  API is required.
 
 
 Conclusion