docs: refresh & structure overhaul

Rework the doc in order to improve the navigation experience and to make
it easier to update the doc:

- simplify structure: docs/{release-notes,user,developer}
- recreate sphinx config file
- switch theme from opnfv to piccolo
- fix minor rst issues
- fix external references
- add missing license headers (add a short header with copyright and
  SPDX license identifier to the files lacking the information.  The
  header is based on https://github.com/david-a-wheeler/spdx-tutorial)

Change-Id: I9a1135a2873d9955beb26760e0cb6c5d6c1326bd
Signed-off-by: Gwenael Lambrouin <gwenael.lambrouin@orange.com>

10 files changed, 0 insertions, 420 deletions

diff --git a/docs/development/building/build.rst b/docs/development/building/build.rst
deleted file mode 100644
index aeda059..0000000
--- a/docs/development/building/build.rst
+++ /dev/null
@@ -1,77 +0,0 @@
-
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) Cisco Systems, Inc
-
-Building containers and VM images
-=================================
-
-NFVbench is delivered as Docker container which is built using the Dockerfile under the docker directory.
-This container includes the following parts:
-
-- TRex traffic generator
-- NFVbench orchestration
-- NFVbench test VM (qcow2)
-
-.. _nfvbench-artefact-versioning:
-
-Versioning
-----------
-These 3 parts are versioned independently and the Dockerfile will determine the combination of versions that
-are packaged in the container for the version associated to the Dockerfile.
-
-The NFVbench version is controlled by the git tag that conforms to the semver version (e.g. "3.3.0").
-This tag controls the version of the Dockerfile used for building the container.
-
-The TRex version is controlled by the TREX_VER variable in Dockerfile (e.g. ENV TREX_VER "v2.56").
-TRex is installed in container from https://github.com/cisco-system-traffic-generator/trex-core/releases
-
-The Test VM version is controlled by the VM_IMAGE_VER variable in Dockerfile (e.g. ENV VM_IMAGE_VER "0.8").
-The VM is extracted from google storage (http://artifacts.opnfv.org)
-
-Updating the VM image
----------------------
-
-When the VM image is changed, its version must be increased in order to distinguish from previous image versions.
-The version strings to change are located in 2 files:
-
-- docker/Dockerfile
-- nfvbench/nfvbenchvm/dib/build-image.sh
-
-Building and uploading the VM image
------------------------------------
-The VM image is built on gerrit verify when the image is not present in google storage.
-It is not uploaded yet on google storage.
-
-The build + upload of the new VM image is done after the review is merged.
-
-For details on how this is done, refer to ./jjb/nfvbench/nfvbench.yaml in the opnfv releng repository.
-
-Building a new NFVbench container image
----------------------------------------
-A new container image can be built and published to Dockerhub by CI/CD by applying a new semver tag to the
-nfvbench repository.
-
-
-Workflow summary
-----------------
-
-NFVbench code has changed:
-
-- commit with gerrit
-- apply a new semver tag to trigger the container image build/publication
-
-VM code has changed:
-
-- update VM version in the 2 locations
-- commit VM changes with gerrit to trigger VM build and publication to google storage
-- IMPORTANT! wait for the VM image to be pushed to google storage before going to the next step
-  (otherwise the container build will fail as it will not find the VM image)
-- apply a new semver tag to trigger the container image build/publication
-
-To increase the TRex version:
-
-- change the Trex version in Dockerfile
-- commit with gerrit
-- apply a new semver tag to trigger the container image build/publication
diff --git a/docs/development/building/index.rst b/docs/development/building/index.rst
deleted file mode 100644
index 8b9d786..0000000
--- a/docs/development/building/index.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) Cisco Systems, Inc
-
-===============================
-OPNFV NFVbench Euphrates Design
-===============================
-
-.. toctree::
-   :maxdepth: 2
-
-   build
-
diff --git a/docs/development/design/design.rst b/docs/development/design/design.rst
deleted file mode 100644
index 75b90f8..0000000
--- a/docs/development/design/design.rst
+++ /dev/null
@@ -1,80 +0,0 @@
-
-
-.. contents::
-   :depth: 3
-   :local:
-
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) Cisco Systems, Inc
-
-
-Introduction
-------------
-
-NFVbench can be decomposed in the following components:
-- Configuration
-- Orchestration:
-
-  - Staging
-  - Traffic generation
-  - Results analysis
-
-Configuration
--------------
-This component is in charge of getting the configuration options from the user and consolidate them with
-the default configuration into a running configuration.
-
-default configuration + user configuration options = running configuration
-
-User configuration can come from:
-- CLI configuration shortcut arguments (e.g --frame-size)
-- CLI configuration file (--config [file])
-- CLI configuration string (--config [string])
-- REST request body
-- custom platform pluging
-
-The precedence order for configuration is (from highest precedence to lowest precedence)
-- CLI configuration or REST configuration
-- custom platform plugin
-- default configuration
-
-The custom platform plugin is an optional python class that can be used to override default configuration options
-with default platform options which can be either hardcoded or calculated at runtime from platform specific sources
-(such as platform deployment configuration files).
-A custom platform plugin class is a child of the parent class nfvbench.config_plugin.ConfigPlugin.
-
-Orchestration
--------------
-Once the configuration is settled, benchmark orchestration is managed by the ChainRunner class (nfvbench.chain_runner.ChainRunner).
-The chain runner will take care of orchestrating the staging, traffic generation and results analysis.
-
-
-Staging
--------
-The staging component is in charge of staging the OpenStack resources that are used for the requested packet path.
-For example, for a PVP packet path, this module will create 2 Neutron networks and one VM instance connected to these 2 networks.
-Multi-chaining and VM placement is also handled by this module.
-
-Main class: nfvbench.chaining.ChainManager
-
-Traffic Generation
-------------------
-The traffic generation component is in charge of contrilling the TRex traffic generator using its python API.
-It includes tasks such as:
-- traffic check end to end to make sure the packet path is clear in both directions before starting a benchmark
-- programming the TRex traffic flows based on requested parameters
-- fixed rate control
-- NDR/PDR binary search
-
-Main class: nfvbench.traffic_client.TrafficClient
-
-
-Traffic Generator Results Analysis
-----------------------------------
-At the end of a traffic generation session, this component collects the results from TRex and packages them in a format that
-is suitable for the various output formats (JSON, REST, file, fluentd).
-In the case of multi-chaining, it handles aggregation of results across chains.
-
-Main class: nfvbench.stats_manager.StatsManager
diff --git a/docs/development/design/index.rst b/docs/development/design/index.rst
deleted file mode 100644
index 0500ca2..0000000
--- a/docs/development/design/index.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) Cisco Systems, Inc
-
-===============================
-OPNFV NFVbench Euphrates Design
-===============================
-
-.. toctree::
-   :maxdepth: 2
-
-   design
-   versioning
-   traffic_desc
-   ndrpdr
diff --git a/docs/development/design/ndrpdr.rst b/docs/development/design/ndrpdr.rst
deleted file mode 100644
index dd769c0..0000000
--- a/docs/development/design/ndrpdr.rst
+++ /dev/null
@@ -1,83 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) Cisco Systems, Inc
-
-NDR/PDR Binary Search
-=====================
-
-The NDR/PDR binary search algorithm used by NFVbench is based on the algorithm used by the
-FD.io CSIT project, with some additional optimizations.
-
-Algorithm Outline
------------------
-
-The ServiceChain class (nfvbench/service_chain.py) is responsible for calculating the NDR/PDR
-or all frame sizes requested in the configuration.
-Calculation for 1 frame size is delegated to the TrafficClient class (nfvbench/traffic_client.py)
-
-Call chain for calculating the NDR-PDR for a list of frame sizes:
-
-- ServiceChain.run()
-    - ServiceChain._get_chain_results()
-        - for every frame size:
-            - ServiceChain.__get_result_per_frame_size()
-                - TrafficClient.get_ndr_pdr()
-                    - TrafficClient.__range_search() recursive binary search
-
-The search range is delimited by a left and right rate (expressed as a % of line rate per direction).
-The search always start at line rate per port, e.g. in the case of 2x10Gbps, the first iteration
-will send 10Gbps of traffic on each port.
-
-The load_epsilon configuration parameter defines the accuracy of the result as a % of line rate.
-The default value of 0.1 indicates for example that the measured NDR and PDR are within 0.1% of line rate of the
-actual NDR/PDR (e.g. 0.1% of 10Gbps is 10Mbps). It also determines how small the search range must be in the binary search.
-Smaller values of load_epsilon will result in more iterations and will take more time but may not
-always be beneficial if the absolute value falls below the precision level of the measurement.
-For example a value of 0.01% would translate to an absolute value of 1Mbps (for a 10Gbps port) or
-around 10kpps (at 64 byte size) which might be too fine grain.
-
-The recursion narrows down the range by half and stops when:
-
-- the range is smaller than the configured load_epsilon value
-- or when the search hits 100% or 0% of line rate
-
-Optimization
-------------
-
-Binary search algorithms assume that the drop rate curve is monotonically increasing with the Tx rate.
-To save time, the algorithm used by NFVbench is capable of calculating the optimal Tx rate for an
-arbitrary list of target maximum drop rates in one pass instead of the usual 1 pass per target maximum drop rate.
-This saves time linearly to the number target drop rates.
-For example, a typical NDR/PDR search will have 2 target maximum drop rates:
-
-- NDR = 0.001%
-- PDR = 0.1%
-
-The binary search will then start with a sorted list of 2 target drop rates: [0.1, 0.001].
-The first part of the binary search will then focus on finding the optimal rate for the first target
-drop rate (0.1%). When found, the current target drop rate is removed from the list and
-iteration continues with the next target drop rate in the list but this time
-starting from the upper/lower range of the previous target drop rate, which saves significant time.
-The binary search continues until the target maximum drop rate list is empty.
-
-Results Granularity
--------------------
-The binary search results contain per direction stats (forward and reverse).
-In the case of multi-chaining, results contain per chain stats.
-The current code only reports aggregated stats (forward + reverse for all chains) but could be enhanced
-to report per chain stats.
-
-
-CPU Limitations
----------------
-One particularity of using a software traffic generator is that the requested Tx rate may not always be met due to
-resource limitations (e.g. CPU is not fast enough to generate a very high load). The algorithm should take this into
-consideration:
-
-- always monitor the actual Tx rate achieved as reported back by the traffic generator
-- actual Tx rate is always <= requested Tx rate
-- the measured drop rate should always be relative to the actual Tx rate
-- if the actual Tx rate is < requested Tx rate and the measured drop rate is already within threshold
-  (<NDR/PDR threshold) then the binary search must stop with proper warning because the actual NDR/PDR
-  might probably be higher than the reported values
diff --git a/docs/development/design/traffic_desc.rst b/docs/development/design/traffic_desc.rst
deleted file mode 100644
index bbd31a6..0000000
--- a/docs/development/design/traffic_desc.rst
+++ /dev/null
@@ -1,84 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) Cisco Systems, Inc
-
-Traffic Description
-===================
-
-The general packet path model followed by NFVbench requires injecting traffic into an arbitrary
-number of service chains, where each service chain is identified by 2 edge networks (left and right).
-In the current multi-chaining model:
-
-- all service chains can either share the same left and right edge networks or can have their own edge networks
-- each port associated to the traffic generator is dedicated to send traffic to one side of the edge networks
-
-If VLAN encapsulation is used, all traffic sent to a port will either have the same VLAN id (shared networks) or distinct VLAN ids (dedicated egde networks)
-
-Basic Packet Description
-------------------------
-
-The code to create the UDP packet is located in TRex.create_pkt() (nfvbench/traffic_gen/trex.py).
-
-NFVbench always generates UDP packets (even when doing L2 forwarding).
-The final size of the frame containing each UDP packet will be based on the requested L2 frame size.
-When taking into account the minimum payload size requirements from the traffic generator for
-the latency streams, the minimum L2 frame size is 64 byte.
-
-Flows Specification
--------------------
-
-Mac Addresses
-.............
-The source MAC address is always the local port MAC address (for each port).
-The destination MAC address is based on the configuration and can be:
-
-- the traffic generator peer port MAC address in the case of L2 loopback at the switch level
-  or when using a loopback cable
-- the dest MAC as specified by the configuration file (EXT chain no ARP)
-- the dest MAC as discovered by ARP (EXT chain)
-- the router MAC as discovered from Neutron API (PVPL3 chain)
-- the VM MAC as dicovered from Neutron API (PVP, PVVP chains)
-
-NFVbench does not currently range on the MAC addresses.
-
-IP addresses
-............
-The source IP address is fixed per chain.
-The destination IP address is variable within a distinct range per chain.
-
-UDP ports
-.........
-The source and destination ports are fixed for all packets and can be set in the configuratoon
-file (default is 53).
-
-Payload User Data
-.................
-The length of the user data is based on the requested L2 frame size and takes into account the
-size of the L2 header - including the VLAN tag if applicable.
-
-
-IMIX Support
-------------
-In the case of IMIX, each direction is made of 4 streams:
-- 1 latency stream
-- 1 stream for each IMIX frame size
-
-The IMIX ratio is encoded into the number of consecutive packets sent by each stream in turn.
-
-Service Chains and Streams
---------------------------
-A stream identifies one "stream" of packets with same characteristics such as rate and destination address.
-NFVbench will create 2 streams per service chain per direction:
-
-- 1 latency stream set to 1000pps
-- 1 main traffic stream set to the requested Tx rate less the latency stream rate (1000pps)
-
-For example, a benchmark with 1 chain (fixed rate) will result in a total of 4 streams.
-A benchmark with 20 chains will results in a total of 80 streams (fixed rate, it is more with IMIX).
-
-The overall flows are split equally between the number of chains by using the appropriate destination
-MAC address.
-
-For example, in the case of 10 chains, 1M flows and fixed rate, there will be a total of 40 streams.
-Each of the 20 non-latency stream will generate packets corresponding to 50,000 flows (unique src/dest address tuples).
diff --git a/docs/development/design/versioning.rst b/docs/development/design/versioning.rst
deleted file mode 100644
index 40e70f2..0000000
--- a/docs/development/design/versioning.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) Cisco Systems, Inc
-
-Versioning
-==========
-
-NFVbench uses semver compatible git tags such as "1.0.0". These tags are also called project tags and applied at important commits on the master branch exclusively.
-Rules for the version numbers follow the semver 2.0 specification (https://semver.org).
-These git tags are applied indepently of the OPNFV release tags which are applied only on the stable release branches (e.g. "opnfv-5.0.0").
-
-In general it is recommeneded to always have a project git version tag associated to any OPNFV release tag content obtained from a sync from master.
-
-NFVbench Docker containers will be versioned based on the NFVbench project tags.
diff --git a/docs/development/index.rst b/docs/development/index.rst
deleted file mode 100644
index 0477154..0000000
--- a/docs/development/index.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) Cisco Systems, Inc
-
-.. toctree::
-   :maxdepth: 3
-
-   overview/index
-   design/index
-   building/index
diff --git a/docs/development/overview/index.rst b/docs/development/overview/index.rst
deleted file mode 100644
index ce99621..0000000
--- a/docs/development/overview/index.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) Cisco Systems, Inc
-
-=============================================
-OPNFV NFVbench Euphrates Overview
-=============================================
-
-.. toctree::
-   :maxdepth: 1
-
-   overview
diff --git a/docs/development/overview/overview.rst b/docs/development/overview/overview.rst
deleted file mode 100644
index 26e19d1..0000000
--- a/docs/development/overview/overview.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) Cisco Systems, Inc
-
-.. contents::
-   :depth: 3
-   :local:
-
-Introduction
-----------------
-NFVbench is a python application that is designed to run in a compact and portable format inside a container and on production pods.
-As such it only uses open sourec software with minimal hardware requirements (just a NIC card that is DPDK compatible).
-Traffic generation is handled by TRex on 2 physical ports (2x10G or higher) forming traffic loops up to VNF level and following
-a path that is common to all NFV applications: external source to top of rack switch(es) to compute node(s) to vswitch (if applicable)
-to VNF(s) and back.
-
-Configuration of benchmarks is through a yaml configuraton file and command line arguments.
-
-Results are available in different formats:
-- text output with tabular results
-- json result in file or in REST reply (most detailed)
-
-Logging is available in a log file.
-
-Benchmark results and logs can be optionally sent to one or more remote fluentd aggeregators using json format.