docs: better docs, mv doxygen to sphinx

This patch refactors the VPP sphinx docs
in order to make it easier to consume
for external readers as well as VPP developers.

It also makes sphinx the single source
of documentation, which simplifies maintenance
and operation.

Most important updates are:

- reformat the existing documentation as rst
- split RELEASE.md and move it into separate rst files
- remove section 'events'
- remove section 'archive'
- remove section 'related projects'
- remove section 'feature by release'
- remove section 'Various links'
- make (Configuration reference, CLI docs,
  developer docs) top level items in the list
- move 'Use Cases' as part of 'About VPP'
- move 'Troubleshooting' as part of 'Getting Started'
- move test framework docs into 'Developer Documentation'
- add a 'Contributing' section for gerrit,
  docs and other contributer related infos
- deprecate doxygen and test-docs targets
- redirect the "make doxygen" target to "make docs"

Type: refactor

Change-Id: I552a5645d5b7964d547f99b1336e2ac24e7c209f
Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>
Signed-off-by: Andrew Yourtchenko <ayourtch@gmail.com>

5 files changed, 666 insertions, 0 deletions

diff --git a/docs/cli-reference/interface/basic.rst b/docs/cli-reference/interface/basic.rst
new file mode 100644
index 00000000000..2d4202dfc57
--- /dev/null
+++ b/docs/cli-reference/interface/basic.rst
@@ -0,0 +1,83 @@
+.. _interface:
+
+.. toctree::
+
+Basic Interface Commands
+=========================
+
+There are several commands that are associated to Basic Interface:
+
+* `Show Interface`_
+* `Clear Interfaces`_
+
+.. note:: For a complete list of CLI Debug commands refer to the Debug CLI section of the `Source Code Documents <https://docs.fd.io/vpp/18.07/clicmd.html>`_ .
+
+.. _showintcommand:
+
+Show Interface
+++++++++++++++++
+Shows software interface information including counters and features.
+
+.. code-block:: shell
+
+    show interface [address|addr|features|feat] [<interface> [<interface> [..]]]
+
+Examples
+--------
+
+Example of how to show the interface counters:
+
+.. code-block:: console
+
+    vpp# show int
+                  Name               Idx       State          Counter          Count
+    TenGigabitEthernet86/0/0          1         up       rx packets               6569213
+                                                         rx bytes              9928352943
+                                                         tx packets                 50384
+                                                         tx bytes                 3329279
+    TenGigabitEthernet86/0/1          2        down
+    VirtualEthernet0/0/0              3         up       rx packets                 50384
+                                                         rx bytes                 3329279
+                                                         tx packets               6569213
+                                                         tx bytes              9928352943
+                                                         drops                       1498
+    local0                            0        down
+
+Example of how to display the interface placement:
+
+.. code-block:: console
+
+    vpp# show interface rx-placement
+    Thread 1 (vpp_wk_0):
+      node dpdk-input:
+        GigabitEthernet7/0/0 queue 0 (polling)
+      node vhost-user-input:
+        VirtualEthernet0/0/12 queue 0 (polling)
+        VirtualEthernet0/0/12 queue 2 (polling)
+        VirtualEthernet0/0/13 queue 0 (polling)
+        VirtualEthernet0/0/13 queue 2 (polling)
+    Thread 2 (vpp_wk_1):
+      node dpdk-input:
+        GigabitEthernet7/0/1 queue 0 (polling)
+      node vhost-user-input:
+        VirtualEthernet0/0/12 queue 1 (polling)
+        VirtualEthernet0/0/12 queue 3 (polling)
+        VirtualEthernet0/0/13 queue 1 (polling)
+        VirtualEthernet0/0/13 queue 3 (polling)
+
+Clear Interfaces
++++++++++++++++++
+Clear the statistics for all interfaces (statistics associated with the
+'*show interface*' command).
+
+.. code-block:: shell
+
+    clear interfaces
+
+Example
+-------
+Example of how to clear the statistics for all interfaces:
+
+.. code-block:: console
+
+    vpp# clear interfaces
diff --git a/docs/cli-reference/interface/create_interface.rst b/docs/cli-reference/interface/create_interface.rst
new file mode 100644
index 00000000000..abd1f40de04
--- /dev/null
+++ b/docs/cli-reference/interface/create_interface.rst
@@ -0,0 +1,223 @@
+.. _interface:
+
+.. toctree::
+
+Create Interfaces Commands
+===========================
+This section contains those interface commands that are associated to creating an interface:
+
+* `Create Host-Interface`_
+* `Create Interface Memif`_
+* `Create Loopback Interface`_
+* `Create Sub-Interfaces`_
+
+.. note:: For a complete list of CLI Debug commands refer to the Debug CLI section of the `Source Code Documents <https://docs.fd.io/vpp/18.07/clicmd.html>`_ .
+
+Create Host-Interface
+++++++++++++++++++++++
+
+.. code-block:: console
+
+    create host-interface name <*ifname*> [*hw-addr <*mac-addr*>]
+
+
+Description
+------------
+
+Create a host interface that will attach to a linux AF_PACKET interface, one side of a veth pair.
+The veth pair must already exist. Once created, a new host interface will exist in VPP with the name
+'host-<*ifname*>', where '<*ifname*>' is the name of the specified veth pair.
+Use the `show interface` command to display host interface details.
+
+This command has the following optional parameters:
+
+    hw-addr <*mac-addr*> - Optional ethernet address, can be in either X:X:X:X:X:X unix or X.X.X cisco format
+
+Example Usage
+-------------
+
+Example of how to create a host interface tied to one side of an existing linux veth pair named vpp1:
+
+	.. code-block:: console
+
+		vpp# create host-interface name vpp1
+
+		host-vpp1
+
+Once the host interface is created, enable the interface using:
+
+	.. code-block:: console
+
+		vpp# set interface state host-vpp1 up
+
+Declaration and Implementation
+-------------------------------
+
+**Declaration:** af_packet_create_command (src/vnet/devices/af_packet/cli.c line 133)
+
+**Implementation:** af_packet_create_command_fn
+
+Create Interface Memif
++++++++++++++++++++++++
+
+.. code-block:: console
+
+    create interface memif [id <*id*>] [socket-id <*socket-id*>] [ring-size <*size*>] [buffer-size <*size*>] [hw-addr <*mac-address*>] <master|slave> [rx-queues <*number*>] [tx-queues <*number*>] [mode ip] [secret <*string*>]
+
+
+Declaration and Implementation
+-------------------------------
+
+**Declaration:** memif_create_command (src/plugins/memif/cli.c line 258)
+
+**Implementation:** memif_create_command_fn
+
+
+Create Loopback Interface
+++++++++++++++++++++++++++
+
+
+Create a loopback interface. Optionally, a MAC Address can be provided. If not provided, de:ad:00:00:00:<*loopId*> will be used.
+
+.. code-block:: console
+
+    create loopback interface [mac <*mac-addr*>] [instance <*instance*>]
+
+
+Example Usage
+--------------
+The following two command syntaxes are equivalent:
+
+	.. code-block:: console
+
+		vpp# loopback create-interface [mac <*mac-addr*>] [instance <*instance*>]
+
+		vpp# create loopback interface [mac <*mac-addr*>] [instance <*instance*>]
+
+Example of how to create a loopback interface:
+
+	.. code-block:: console
+
+		vpp# create loopback interface
+
+Declaration and Implementation
+-------------------------------
+
+**Declaration:** create_loopback_interface_command (src/vnet/ethernet/interface.c line 879)
+
+**Implementation:** create_simulated_ethernet_interfaces
+
+
+Create Sub-Interfaces
+++++++++++++++++++++++
+
+This command is used to add VLAN IDs to interfaces, also known as
+subinterfaces. The primary input to this command is the *interface*
+and *subId* (subinterface Id) parameters. If no additional VLAN ID is
+provide, the VLAN ID is assumed to be the *subId*. The VLAN ID and
+*subId* can be different, but this is not recommended.
+
+This command has several variations:
+
+-  **create sub-interfaces** <*interface*> <*subId*> - Create a subinterface
+   to process packets with a given 802.1q VLAN ID (same value as the
+   *subId*).
+-  **create sub-interfaces** <*interface*> <*subId*> default - Adding the
+   *default* parameter indicates that packets with VLAN IDs that do
+   not match any other subinterfaces should be sent to this
+   subinterface.
+-  **create sub-interfaces** <*interface*> <*subId*> untagged - Adding the
+   *untagged* parameter indicates that packets no VLAN IDs should be
+   sent to this subinterface.
+-  **create sub-interfaces** <*interface*> <*subId*>-<*subId*> - Create a
+   range of subinterfaces to handle a range of VLAN IDs.
+-  **create sub-interfaces** <*interface*> <*subId*> dot1q|dot1ad <*vlanId*>|any
+   [exact-match] - Use this command to explicitly specify the outer VLAN ID,
+   or to make the VLAN ID different from the *subId*.
+-  **create sub-interfaces** <*interface*> <*subId*> dot1q|dot1ad <*vlanId*>|any
+   inner-dot1q <*vlanId*>|any [exact-match] - Use this command to
+   specify the outer VLAN ID and the inner VLAN ID.
+
+When *dot1q* or *dot1ad* is explicitly entered, subinterfaces can be
+configured as either *exact-match* or *non-exact match*. *Non-exact match* is
+the CLI default. If *exact-match* is specified, packets must have the
+same number of VLAN tags as the configuration. For *non-exact-match*,
+packets must at least that number of tags. L3 (routed) interfaces must
+be configured as exact-match. L2 interfaces are typically configured as
+non-exact-match. If *dot1q* or *dot1ad* is NOT entered, then the
+default behavior is *exact-match*.
+
+Use the **show interface** command to display all subinterfaces.
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+    create sub-interfaces <interface> {<subId> [default|untagged]} | {<subId>-<subId>} | {<subId> dot1q|dot1ad <vlanId>|any [inner-dot1q <vlanId>|any] [exact-match]}
+
+Example Usage
+--------------
+
+Example of how to create a VLAN subinterface 11 to process packets on 802.1q VLAN ID 11:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 11
+
+The previous example is shorthand and is equivalent to:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1q 11 exact-match
+
+Example of how to create a subinterface number that is different from the VLAN ID:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100
+
+Examples of how to create q-in-q and q-in-any subinterfaces:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100 inner-dot1q 200
+    vpp# create sub-interfaces GigabitEthernet2/0/0 12 dot1q 100 inner-dot1q any
+
+Examples of how to create dot1ad interfaces:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1ad 11
+    vpp# create sub-interfaces GigabitEthernet2/0/0 12 dot1ad 100 inner-dot1q 200
+
+Examples of *exact-match* versus non-exact match. A packet with outer VLAN 100 and inner VLAN 200 would match this interface, because the default is non-exact match:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 5 dot1q 100
+
+However, the same packet would NOT match this interface because *exact-match* is specified and only one VLAN is configured, but packet contains two VLANs:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 5 dot1q 100 exact-match
+
+Example of how to created a subinterface to process untagged packets:
+
+.. code-block:: console
+
+   vpp# create sub-interfaces GigabitEthernet2/0/0 5 untagged
+
+Example of how to created a subinterface to process any packet with a VLAN ID that does not match any other subinterface:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 7 default
+
+When subinterfaces are created, they are in the down state. Example of how to enable a newly created subinterface:
+
+.. code-block:: console
+
+    vpp# set interface GigabitEthernet2/0/0.7 up
+
diff --git a/docs/cli-reference/interface/hardware.rst b/docs/cli-reference/interface/hardware.rst
new file mode 100644
index 00000000000..0d124385fac
--- /dev/null
+++ b/docs/cli-reference/interface/hardware.rst
@@ -0,0 +1,161 @@
+.. _interface:
+
+.. toctree::
+
+Hardware-Interfaces Commands
+============================
+This section contains those interface commands that are related to hardware-interfaces:
+
+
+* `Show Bridge-Domain`_
+* `Show Hardware-Interfaces`_
+* `Clear Hardware-Interfaces`_
+
+.. note:: For a complete list of CLI Debug commands refer to the Debug CLI section of the `Source Code Documents <https://docs.fd.io/vpp/18.07/clicmd.html>`_ .
+
+Show Bridge-Domain
++++++++++++++++++++
+
+Show a summary of all the bridge-domain instances or detailed view of a single bridge-domain.
+Bridge-domains are created by adding an interface to a bridge using the **set interface l2 bridge** command.
+
+
+.. code-block:: console
+
+    show bridge-domain [*bridge-domain-id* [detail|int|arp| *bd-tag* ]]
+
+
+Example Usage
+-------------
+.. code-block:: console
+
+    Example of displaying all bridge-domains:
+
+    vpp# show bridge-domain
+
+     ID   Index   Learning   U-Forwrd   UU-Flood   Flooding   ARP-Term     BVI-Intf
+     0      0        off        off        off        off        off        local0
+    200     1        on         on         on         on         off          N/A
+
+    Example of displaying details of a single bridge-domains:
+
+    vpp# show bridge-domain 200 detail
+
+     ID   Index   Learning   U-Forwrd   UU-Flood   Flooding   ARP-Term     BVI-Intf
+    200     1        on         on         on         on         off          N/A
+
+             Interface           Index  SHG  BVI        VLAN-Tag-Rewrite
+     GigabitEthernet0/8/0.200      3     0    -               none
+     GigabitEthernet0/9/0.200      4     0    -               none
+
+Declaration and Implementation
+------------------------------
+
+**Declaration:** bd_show_cli (src/vnet/l2/l2_bd.c line 1151)
+
+**Implementation:** bd_show
+
+Show Hardware-Interfaces
++++++++++++++++++++++++++
+Display more detailed information about all or a list of given
+interfaces. The verboseness of the output can be controlled by the
+following optional parameters:
+
+-  **brief**: Only show name, index and state (default for bonded
+   interfaces).
+-  **verbose**: Also display additional attributes (default for all other
+   interfaces).
+-  **detail**: Also display all remaining attributes and extended
+   statistics.
+
+.. note::
+	To limit the output of the command to bonded interfaces and their
+	slave interfaces, use the '*bond*' optional parameter.
+
+
+.. code-block:: shell
+
+    show hardware-interfaces [brief|verbose|detail] [bond] [<interface> [<interface> [..]]] [<sw_idx> [<sw_idx> [..]]].
+
+
+Examples
+--------
+Example of how to display default data for all interfaces:
+
+.. code-block:: console
+
+    vpp# show hardware-interfaces
+                  Name                Idx   Link  Hardware
+    GigabitEthernet7/0/0               1     up   GigabitEthernet7/0/0
+      Ethernet address ec:f4:bb:c0:bc:fc
+      Intel e1000
+        carrier up full duplex speed 1000 mtu 9216
+        rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
+        cpu socket 0
+    GigabitEthernet7/0/1               2     up   GigabitEthernet7/0/1
+      Ethernet address ec:f4:bb:c0:bc:fd
+      Intel e1000
+        carrier up full duplex speed 1000 mtu 9216
+        rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
+        cpu socket 0
+    VirtualEthernet0/0/0               3     up   VirtualEthernet0/0/0
+      Ethernet address 02:fe:a5:a9:8b:8e
+    VirtualEthernet0/0/1               4     up   VirtualEthernet0/0/1
+      Ethernet address 02:fe:c0:4e:3b:b0
+    VirtualEthernet0/0/2               5     up   VirtualEthernet0/0/2
+      Ethernet address 02:fe:1f:73:92:81
+    VirtualEthernet0/0/3               6     up   VirtualEthernet0/0/3
+      Ethernet address 02:fe:f2:25:c4:68
+    local0                             0    down  local0
+      local
+
+Example of how to display *verbose* data for an interface by name and software index
+(where 2 is the software index):
+
+.. code-block:: console
+
+    vpp# show hardware-interfaces GigabitEthernet7/0/0 2 verbose
+                   Name                Idx   Link  Hardware
+    GigabitEthernet7/0/0               1     up   GigabitEthernet7/0/0
+      Ethernet address ec:f4:bb:c0:bc:fc
+      Intel e1000
+        carrier up full duplex speed 1000 mtu 9216
+        rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
+        cpu socket 0
+    GigabitEthernet7/0/1               2    down  GigabitEthernet7/0/1
+      Ethernet address ec:f4:bb:c0:bc:fd
+      Intel e1000
+        carrier up full duplex speed 1000 mtu 9216
+        rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
+        cpu socket 0
+
+Clear Hardware-Interfaces
++++++++++++++++++++++++++
+
+Clear the extended statistics for all or a list of given interfaces
+(statistics associated with the **show hardware-interfaces** command).
+
+
+.. code-block:: shell
+
+    clear hardware-interfaces [<interface> [<interface> [..]]] [<sw_idx> [<sw_idx> [..]]].
+
+
+Examples
+--------
+
+Example of how to clear the extended statistics for all interfaces:
+
+
+.. code-block:: console
+
+        vpp# clear hardware-interfaces
+
+Example of how to clear the extended statistics for an interface by name and software index
+(where 2 is the software index):
+
+.. code-block:: console
+
+        vpp# clear hardware-interfaces GigabitEthernet7/0/0 2
+
+
diff --git a/docs/cli-reference/interface/index.rst b/docs/cli-reference/interface/index.rst
new file mode 100644
index 00000000000..7fca8f11df2
--- /dev/null
+++ b/docs/cli-reference/interface/index.rst
@@ -0,0 +1,17 @@
+.. _interface:
+
+.. note:: For a complete list of CLI Debug commands refer to the Debug CLI section of the `Source Code Documents <https://docs.fd.io/vpp/18.07/clicmd.html>`_ .
+
+.. _intcommands:
+
+Interface Commands
+==================
+This section identifies the following types of interface commands:
+
+.. toctree::
+   :maxdepth: 2
+
+   basic
+   hardware
+   create_interface
+   setinterface
diff --git a/docs/cli-reference/interface/setinterface.rst b/docs/cli-reference/interface/setinterface.rst
new file mode 100644
index 00000000000..7eb14adf455
--- /dev/null
+++ b/docs/cli-reference/interface/setinterface.rst
@@ -0,0 +1,182 @@
+======================
+Set Interface Commands
+======================
+
+This section covers those commands that are related to setting an
+interface:
+
+-  `Set Interface IP Address <#set-interface-ip-address>`__
+-  `Set Interface L2 Bridge <#set-interface-l2-bridge>`__
+-  `Set Interface MTU <#set-interface-mtu>`__
+-  `Set Interface Promiscuous <#set-interface-promiscuous>`__
+-  `Set Interface State <#set-interface-state>`__
+
+.. note::
+
+   For a complete list of CLI Debug commands refer to the Debug CLI
+   section of the `Source Code
+   Documents <https://docs.fd.io/vpp/18.07/clicmd.html>`__ .
+
+Set Interface IP Address
+========================
+
+.. code:: console
+
+   set interface ip address [del] <*interface*> <*ip-addr*>/<*mask*> | [all]
+
+Add an IP Address to an interface or remove and IP Address from an
+interface. The IP Address can be an IPv4 or an IPv6 address. Interfaces
+may have multiple IPv4 and IPv6 addresses. There is no concept of
+primary vs. secondary interface addresses; they're just addresses.
+
+To display the addresses associated with a given interface, use the
+command **show interface address** <*interface*>.
+
+.. note::
+
+   The debug CLI does not enforce classful mask-width / addressing
+   constraints.
+
+Example Usage
+-------------
+
+An example of how to add an IPv4 address to an interface:
+
+.. code:: console
+
+   vpp# set interface ip address GigabitEthernet2/0/0 172.16.2.12/24
+
+An example of how to add an IPv6 address to an interface:
+
+.. code:: console
+
+   vpp# set interface ip address GigabitEthernet2/0/0 ::a:1:1:0:7/126
+
+To delete a specific interface ip address:
+
+.. code:: console
+
+   vpp# set interface ip address GigabitEthernet2/0/0 172.16.2.12/24 del
+
+To delete all interfaces addresses (IPv4 and IPv6):
+
+.. code:: console
+
+   vpp# set interface ip address GigabitEthernet2/0/0 del all
+
+Declaration and Implementation
+------------------------------
+
+**Declaration:** set_interface_ip_address_command
+(src/vnet/ip/ip46_cli.c line 216)
+
+**Implementation:** add_del_ip_address
+
+Set Interface L2 Bridge
+=======================
+
+.. code:: console
+
+    set interface l2 bridge <*interface*> <*bridge-domain-id*> [bvi|uu-fwd]
+    [shg]
+
+Use this command put an interface into Layer 2 bridge domain. If a
+bridge-domain with the provided bridge-domain-id does not exist, it will
+be created. Interfaces in a bridge-domain forward packets to other
+interfaces in the same bridge-domain based on destination mac address.
+To remove an interface from a the Layer 2 bridge domain, put the
+interface in a different mode, for example Layer 3 mode.
+
+Optionally, an interface can be added to a Layer 2 bridge-domain as a
+Bridged Virtual Interface (bvi). Only one interface in a Layer 2
+bridge-domain can be a bvi.
+
+Optionally, a split-horizon group can also be specified. This defaults
+to 0 if not specified.
+
+.. _example-usage-1:
+
+Example Usage
+-------------
+
+Example of how to configure a Layer 2 bridge-domain with three
+interfaces (where 200 is the bridge-domain-id):
+
+.. code:: console
+
+   vpp# set interface l2 bridge GigabitEthernet0/8/0.200 200
+
+This interface is added a BVI interface:
+
+.. code:: console
+
+   vpp# set interface l2 bridge GigabitEthernet0/9/0.200 200 bvi
+
+This interface also has a split-horizon group of 1 specified:
+
+.. code:: console
+
+   vpp# set interface l2 bridge GigabitEthernet0/a/0.200 200 1
+
+Example of how to remove an interface from a Layer2 bridge-domain:
+
+.. code:: console
+
+   vpp# set interface l3 GigabitEthernet0/a/0.200
+
+.. _declaration-and-implementation-1:
+
+Declaration and Implementation
+------------------------------
+
+**Declaration:** int_l2_bridge_cli (src/vnet/l2/l2_input.c line 949)
+
+**Implementation:** int_l2_bridge
+
+Set Interface MTU
+=================
+
+.. code:: shell
+
+   set interface mtu [packet|ip4|ip6|mpls] <value> <interface>
+
+Set Interface Promiscuous
+=========================
+
+.. code:: shell
+
+   set interface promiscuous [on|off] <interface>.
+
+.. _setintstate:
+
+Set Interface State
+===================
+
+This command is used to change the admin state (up/down) of an
+interface.
+
+If an interface is down, the optional *punt* flag can also be set. The
+*punt* flag implies the interface is disabled for forwarding but punt
+all traffic to slow-path. Use the *enable* flag to clear *punt* flag
+(interface is still down).
+
+.. code:: shell
+
+   set interface state <interface> [up|down|punt|enable].
+
+.. _example-usage-2:
+
+Example Usage
+-------------
+
+Example of how to configure the admin state of an interface to **up**:
+
+.. code:: console
+
+   vpp# set interface state GigabitEthernet2/0/0 up
+
+Example of how to configure the admin state of an interface to **down**:
+
+.. code:: console
+
+   vpp# set interface state GigabitEthernet2/0/0 down