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)

5 files changed, 65 insertions, 61 deletions

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