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>

8 files changed, 0 insertions, 411 deletions

diff --git a/docs/reference/vppvagrant/VagrantVMSetup.rst b/docs/reference/vppvagrant/VagrantVMSetup.rst
deleted file mode 100644
index c13a87e30f9..00000000000
--- a/docs/reference/vppvagrant/VagrantVMSetup.rst
+++ /dev/null
@@ -1,56 +0,0 @@
-.. _VagrantVMSetup:
-
-.. toctree::
-
-Accessing your VM
-^^^^^^^^^^^^^^^^^
-ssh into the newly created box:
-
-.. code-block:: shell
-
-    $ vagrant ssh <id>
-
-Sample output looks like:
-
-.. code-block:: console
-
-  $ vagrant ssh c1c
-  Welcome to Ubuntu 16.04 LTS (GNU/Linux 4.4.0-21-generic x86_64)
-
-   * Documentation:  https://help.ubuntu.com/
-  Last login: Mon Jun 25 08:05:38 2018 from 10.0.2.2
-  vagrant@localhost:~$
-
-
-.. note::
-  
-  Type **exit** in the command-line if you want to exit the VM.
-
-Become the root with:
-
-.. code-block:: shell
-
-    $ sudo bash
-
-Now *install* VPP in the VM. Keep in mind that VPP is already built (but not yet installed) at this point based on the commands from the provisioned script *build.sh*. 
-
-When you ssh into your Vagrant box you will be placed in the directory */home/vagrant*. Change directories to */vpp/build-root*, and run these commands to install VPP based on your OS and architecture:
-
-For Ubuntu systems:
-
-.. code-block:: shell
-    
-    # dpkg -i *.deb
-
-For CentOS systems:
-
-.. code-block:: shell
-    
-    # rpm -Uvh *.rpm
-
-
-Since VPP is now installed, you can start running VPP with:
-
-.. code-block:: shell
-  
-    # service vpp start
diff --git a/docs/reference/vppvagrant/Vagrantfile b/docs/reference/vppvagrant/Vagrantfile
deleted file mode 100644
index 642969faa63..00000000000
--- a/docs/reference/vppvagrant/Vagrantfile
+++ /dev/null
@@ -1,112 +0,0 @@
-# -*- mode: ruby -*-
-# vi: set ft=ruby :
-
-Vagrant.configure(2) do |config|
-
-  # Pick the right distro and bootstrap, default is ubuntu1604
-  distro = ( ENV['VPP_VAGRANT_DISTRO'] || "ubuntu1604")
-  if distro == 'centos7'
-    config.vm.box = "centos/7"
-    config.vm.box_version = "1708.01"
-    config.ssh.insert_key = false
-  else
-    config.vm.box = "puppetlabs/ubuntu-16.04-64-nocm"
-  end
-  config.vm.box_check_update = false
-
-  config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"update.sh")
-  config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"build.sh"), :args => "/vpp vagrant"
-
-  post_build = ( ENV['VPP_VAGRANT_POST_BUILD'] )
-  if post_build == "test"
-    config.vm.provision "shell", inline: "echo Testing VPP; cd /vpp; make test"
-  elsif post_build == "install"
-    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"install.sh"), :args => "/vpp"
-    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"clearinterfaces.sh")
-    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"run.sh")
-  end
-
-  # Add .gnupg dir in so folks can sign patches
-  # Note, as gnupg puts socket files in that dir, we have
-  # to be cautious and make sure we are dealing with a plain file
-  homedir = File.expand_path("~/")
-  Dir["#{homedir}/.gnupg/**/*"].each do |fname|
-    if File.file?(fname)
-      destname = fname.sub(Regexp.escape("#{homedir}/"),'')
-      config.vm.provision "file", source: fname, destination: destname
-    end
-  end
-
-  # Copy in the .gitconfig if it exists
-  if File.file?(File.expand_path("~/.gitconfig"))
-    config.vm.provision  "file", source: "~/.gitconfig", destination: ".gitconfig"
-  end
-
-  # vagrant-cachier caches apt/yum etc to speed subsequent
-  # vagrant up
-  # to enable, run
-  # vagrant plugin install vagrant-cachier
-  #
-  if Vagrant.has_plugin?("vagrant-cachier")
-    config.cache.scope = :box
-  end
-
-  # Define some physical ports for your VMs to be used by DPDK
-  nics = (ENV['VPP_VAGRANT_NICS'] || "2").to_i(10)
-  for i in 1..nics
-    config.vm.network "private_network", type: "dhcp"
-  end
-
-  # use http proxy if available
-  if ENV['http_proxy'] && Vagrant.has_plugin?("vagrant-proxyconf")
-   config.proxy.http     = ENV['http_proxy']
-   config.proxy.https    = ENV['https_proxy']
-   config.proxy.no_proxy = "localhost,127.0.0.1"
-  end
-
-  vmcpu=(ENV['VPP_VAGRANT_VMCPU'] || 2)
-  vmram=(ENV['VPP_VAGRANT_VMRAM'] || 4096)
-
-  config.ssh.forward_agent = true
-  config.ssh.forward_x11 = true
-
-  config.vm.provider "virtualbox" do |vb|
-      vb.customize ["modifyvm", :id, "--ioapic", "on"]
-      vb.memory = "#{vmram}"
-      vb.cpus = "#{vmcpu}"
-
-      # rsync the vpp directory if provision hasn't happened yet
-      unless File.exist? (".vagrant/machines/default/virtualbox/action_provision")
-        config.vm.synced_folder "../../", "/vpp", type: "rsync",
-         rsync__auto: false,
-         rsync__exclude: [
-          "build-root/build*/",
-          "build-root/install*/",
-          "build-root/images*/",
-          "build-root/*.deb",
-          "build-root/*.rpm",
-          "build-root/*.changes",
-          "build-root/python",
-          "build-root/deb/debian/*.dkms",
-          "build-root/deb/debian/*.install",
-          "build-root/deb/debian/changes",
-          "build-root/tools"]
-      end
-
-      #support for the SSE4.x instruction is required in some versions of VB.
-      vb.customize ["setextradata", :id, "VBoxInternal/CPUM/SSE4.1", "1"]
-      vb.customize ["setextradata", :id, "VBoxInternal/CPUM/SSE4.2", "1"]
-  end
-  config.vm.provider "vmware_fusion" do |fusion,override|
-    fusion.vmx["memsize"] = "#{vmram}"
-    fusion.vmx["numvcpus"] = "#{vmcpu}"
-  end
-  config.vm.provider "libvirt" do |lv|
-    lv.memory = "#{vmram}"
-    lv.cpus = "#{vmcpu}"
-  end
-  config.vm.provider "vmware_workstation" do |vws,override|
-    vws.vmx["memsize"] = "#{vmram}"
-    vws.vmx["numvcpus"] = "#{vmcpu}"
-  end
-end
diff --git a/docs/reference/vppvagrant/boxSetup.rst b/docs/reference/vppvagrant/boxSetup.rst
deleted file mode 100644
index ed20c9d37c1..00000000000
--- a/docs/reference/vppvagrant/boxSetup.rst
+++ /dev/null
@@ -1,122 +0,0 @@
-.. _boxSetup:
-
-.. toctree::
-
-
-Vagrantfiles
-============
-
-A `Vagrantfile <https://www.vagrantup.com/docs/vagrantfile/>`_ contains the box and provision configuration settings for your VM. The syntax of Vagrantfiles is Ruby (Ruby experience is not necessary).
-
-The command **vagrant up** creates a *Vagrant Box* based on your Vagrantfile. A Vagrant box is one of the motivations for using Vagrant - its a "development-ready box" that can be copied to other machines to recreate the same environment. 
-
-It's common for people to think that a Vagrant box *is* the VM. But rather, the VM is *inside* a Vagrant box, with the box containing additional configuration options you can set, such as VM options, scripts to run on boot, etc.
-
-This `Vagrant website for boxes <https://app.vagrantup.com/boxes/search>`_  shows you how to configure a basic Vagrantfile for your specific OS and VM software.
-
-
-Box configuration 
-_________________
-
-
-Looking at the :ref:`vppVagrantfile`, we can see that the default OS is Ubuntu 16.04 (since the variable *distro* equals *ubuntu1604* if there is no VPP_VAGRANT_DISTRO variable set - thus the **else** case is executed.)
-
-.. code-block:: ruby
-
-    # -*- mode: ruby -*-
-    # vi: set ft=ruby :
-
-    Vagrant.configure(2) do |config|
-
-      # Pick the right distro and bootstrap, default is ubuntu1604
-      distro = ( ENV['VPP_VAGRANT_DISTRO'] || "ubuntu1604")
-      if distro == 'centos7'
-        config.vm.box = "centos/7"
-        config.vm.box_version = "1708.01"
-        config.ssh.insert_key = false
-      else
-        config.vm.box = "puppetlabs/ubuntu-16.04-64-nocm"
-
-As mentioned in the previous page, you can specify which OS and VM provider you want for your Vagrant box from the `Vagrant boxes page <https://app.vagrantup.com/boxes/search>`_, and setting your ENV variable appropriately in *env.sh*.
-
-Next in the Vagrantfile, you see some *config.vm.provision* commands. As paraphrased from `Basic usage of Provisioners <https://www.vagrantup.com/docs/provisioning/basic_usage.html>`_, by default these are only run *once* - during the first boot of the box.
-
-.. code-block:: ruby
-
-    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"update.sh")
-    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"build.sh"), :args => "/vpp vagrant"
-
-The two lines above set the VM to run two scripts during its first bootup: an update script *update.sh* that does basic updating and installation of some useful tools, as well as *build.sh* that builds (but does **not** install) VPP in the VM. You can view these scripts on your own for more detail on the commands used.
-
-
-Looking further in the :ref:`vppVagrantfile`, you can see more Ruby variables being set to ENV's or to a default value:
-
-.. code-block:: ruby
-
-    # Define some physical ports for your VMs to be used by DPDK
-    nics = (ENV['VPP_VAGRANT_NICS'] || "2").to_i(10)
-    for i in 1..nics
-      config.vm.network "private_network", type: "dhcp"
-    end
-
-    # use http proxy if available
-    if ENV['http_proxy'] && Vagrant.has_plugin?("vagrant-proxyconf")
-     config.proxy.http     = ENV['http_proxy']
-     config.proxy.https    = ENV['https_proxy']
-     config.proxy.no_proxy = "localhost,127.0.0.1"
-    end
-
-    vmcpu=(ENV['VPP_VAGRANT_VMCPU'] || 2)
-    vmram=(ENV['VPP_VAGRANT_VMRAM'] || 4096)
-
-
-You can see how the box or VM is configured, such as the amount of NICs (defaults to 3 NICs: 1 x NAT - host access and 2 x VPP DPDK enabled), CPUs (defaults to 2), and RAM (defaults to 4096 MB).
-
-
-Box bootup
-__________
-
-
-Once you're satisfied with your *Vagrantfile*, boot the box with:
-
-.. code-block:: shell
-
-    $ vagrant up
-
-Doing this above command will take quite some time, since you are installing a VM and building VPP. Take a break and get some scooby snacks while you wait.
-
-To confirm it is up, show the status and information of Vagrant boxes with: 
-
-.. code-block:: console
-
-  $ vagrant global-status
-  id       name    provider   state    directory                                           
-  -----------------------------------------------------------------------------------------
-  d90a17b  default virtualbox poweroff /home/centos/andrew-vpp/vppsb/vpp-userdemo          
-  77b085e  default virtualbox poweroff /home/centos/andrew-vpp/vppsb2/vpp-userdemo         
-  c1c8952  default virtualbox poweroff /home/centos/andrew-vpp/testingVPPSB/extras/vagrant 
-  c199140  default virtualbox running  /home/centos/andrew-vpp/vppsb3/vpp-userdemo 
-
-  You will have only one machine running, but I have multiple as shown above.
-
-.. note::
-
-  To poweroff your VM, type:
-
-  .. code-block:: shell
-
-     $ vagrant halt <id>
-
-  To resume your VM, type:
-
-  .. code-block:: shell
-
-     $ vagrant resume <id>
-     
-  To destroy your VM, type:
-
-  .. code-block:: shell
-
-     $ vagrant destroy <id>
-
-  Note that "destroying" a VM does not erase the box, but rather destroys all resources allocated for that VM. For other Vagrant commands, such as destroying a box, refer to the `Vagrant CLI Page <https://www.vagrantup.com/docs/cli/>`_.
diff --git a/docs/reference/vppvagrant/index.rst b/docs/reference/vppvagrant/index.rst
deleted file mode 100644
index 04da9e3f022..00000000000
--- a/docs/reference/vppvagrant/index.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-.. _vppvagrant:
-
-VM's with Vagrant
-=================
-
-This reference guide will cover using Vagrant to boot a VM (virtual machine).
-
-.. toctree::
-
-    vagrantOverview
-    installingVboxVagrant
-    settingENV
-    boxSetup
-    VagrantVMSetup
-    vppVagrantfile
diff --git a/docs/reference/vppvagrant/installingVboxVagrant.rst b/docs/reference/vppvagrant/installingVboxVagrant.rst
deleted file mode 100644
index 326312899b4..00000000000
--- a/docs/reference/vppvagrant/installingVboxVagrant.rst
+++ /dev/null
@@ -1,38 +0,0 @@
-.. _installingVboxVagrant:
-
-Installing Vbox and Vagrant
-===========================
-
-Installing VirtualBox
-_____________________
-
-First download VirtualBox, which is virtualization software for creating VM's.
-
-If you're on CentOS, follow the `steps here <https://wiki.centos.org/HowTos/Virtualization/VirtualBox>`_.
-
-
-If you're on Ubuntu, perform:
-
-.. code-block:: shell
-
-   $ sudo apt-get install virtualbox 
-
-If you want to download a newer version of Virtual Box or one specific to your OS and architecture, go to the `Virtual Box download page <https://www.virtualbox.org/wiki/Downloads>`_.
-
-Installing Vagrant
-__________________
-
-Here we are on a 64-bit version of CentOS, downloading and installing Vagrant 2.1.2:
-
-.. code-block:: shell
-
-   $ yum -y install https://releases.hashicorp.com/vagrant/2.1.2/vagrant_2.1.2_x86_64.rpm
-
-This is a similar command, but on a 64-bit version of Debian:
-
-.. code-block:: shell
-
-   $ sudo apt-get install https://releases.hashicorp.com/vagrant/2.1.2/vagrant_2.1.2_x86_64.deb
-
-
-If you want to download a newer version of Vagrant or one specific to your OS and architecture, go to the `Vagrant download page <https://www.vagrantup.com/downloads.html>`_.
diff --git a/docs/reference/vppvagrant/settingENV.rst b/docs/reference/vppvagrant/settingENV.rst
deleted file mode 100644
index 8bd7847d36c..00000000000
--- a/docs/reference/vppvagrant/settingENV.rst
+++ /dev/null
@@ -1,29 +0,0 @@
-.. _settingENV:
-
-.. toctree::
-
-
-Setting your ENV Variables
-==========================
-
-
-The :ref:`vppVagrantfile` used in the VPP repo sets the configuration options based on your ENV (environment) variables, or to default the configuration at specified values if your ENV variables are not initialized (if you did not run the *env.sh* script found below). 
-
-This is the *env.sh* script found in *vpp/extras/vagrant*. When run, the script sets ENV variables using the **export** command.
-
-.. code-block:: bash
-
-    export VPP_VAGRANT_DISTRO="ubuntu1604"
-    export VPP_VAGRANT_NICS=2
-    export VPP_VAGRANT_VMCPU=4
-    export VPP_VAGRANT_VMRAM=4096 
-
-In the :ref:`vppVagrantfile`, you can see these same ENV variables used (discussed on the next page).
-
-Adding your own ENV variables is easy. For example, if you wanted to setup proxies for your VM, you would add to this file the **export** commands found in the :ref:`building VPP commands section <building>`. Note that this only works if the ENV variable is defined in the :ref:`vppVagrantfile`.
-
-Once you're finished with *env.sh* script, and you are in the directory containing *env.sh*, run the script to set the ENV variables with:
-
-.. code-block:: shell
-   
-   $ source ./env.sh
diff --git a/docs/reference/vppvagrant/vagrantOverview.rst b/docs/reference/vppvagrant/vagrantOverview.rst
deleted file mode 100644
index 882b8a68cfd..00000000000
--- a/docs/reference/vppvagrant/vagrantOverview.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-.. _vagrantOverview:
-
-.. toctree::
-
-Overview
-^^^^^^^^
-
-This guide shows how the VPP :ref:`vppVagrantfile` interacts with shell scripts to configure a `Vagrant box <https://www.vagrantup.com/docs/boxes.html>`_ that boots a VM with VPP. 
-
-.. _prereqlabel:
-
-Prerequisites
-_____________
-
-You have the `FD.io VPP repo <https://github.com/FDio/vpp>`_ cloned locally on your machine. 
-
-
-This guide will refer to the following files from that repo: *Vagrantfile, build.sh, env.sh, and update.sh*.
-
-
-
-
-
-
-
diff --git a/docs/reference/vppvagrant/vppVagrantfile.rst b/docs/reference/vppvagrant/vppVagrantfile.rst
deleted file mode 100644
index d3c705542bd..00000000000
--- a/docs/reference/vppvagrant/vppVagrantfile.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-.. _vppVagrantfile:
-
-Vagrant File
-============
-
-This is the Vagrantfile provided in the `Git VPP repo <https://github.com/FDio/vpp/blob/master/extras/vagrant/Vagrantfile>`_.
-
-.. literalinclude:: Vagrantfile
-   :language: Ruby
-   :emphasize-lines: 4-17, 20-21, 57-71
-
-
-
-.. toctree::