From 9ad39c026c8a3c945a7003c4aa4f5cb1d4c80160 Mon Sep 17 00:00:00 2001 From: Nathan Skrzypczak Date: Thu, 19 Aug 2021 11:38:06 +0200 Subject: 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 Signed-off-by: Andrew Yourtchenko --- docs/gettingstarted/progressivevpp/index.rst | 2 -- docs/gettingstarted/progressivevpp/interface.rst | 4 +-- docs/gettingstarted/progressivevpp/routing.rst | 8 +++--- docs/gettingstarted/progressivevpp/runningvpp.rst | 2 +- .../progressivevpp/settingupenvironment.rst | 15 +++++------ docs/gettingstarted/progressivevpp/switching.rst | 16 ++++++------ docs/gettingstarted/progressivevpp/traces.rst | 30 +++++++++++----------- .../progressivevpp/twovppinstances.rst | 4 +-- 8 files changed, 39 insertions(+), 42 deletions(-) (limited to 'docs/gettingstarted/progressivevpp') diff --git a/docs/gettingstarted/progressivevpp/index.rst b/docs/gettingstarted/progressivevpp/index.rst index ab257f25258..7d1a2e2b237 100644 --- a/docs/gettingstarted/progressivevpp/index.rst +++ b/docs/gettingstarted/progressivevpp/index.rst @@ -14,8 +14,6 @@ will discuss basic operations, and the state of a running FD.io VPP on a system. This is **not** intended to be a 'How to Run in a Production Environment' set of instructions. -For more information on using VPP with Virtual Box/Vagrant, please refer to :ref:`vppvagrant` - .. toctree:: settingupenvironment.rst diff --git a/docs/gettingstarted/progressivevpp/interface.rst b/docs/gettingstarted/progressivevpp/interface.rst index 112eaa974b4..7e35ca870f9 100644 --- a/docs/gettingstarted/progressivevpp/interface.rst +++ b/docs/gettingstarted/progressivevpp/interface.rst @@ -41,7 +41,7 @@ Initial State The initial state here is presumed to be the final state from the previous sections of the tutorial. - + Create veth interfaces on host ------------------------------- @@ -104,7 +104,7 @@ command: __/ __/ _ \ (_)__ | | / / _ \/ _ \ _/ _// // / / / _ \ | |/ / ___/ ___/ /_/ /____(_)_/\___/ |___/_/ /_/ - + vpp# Create a host interface attached to **vpp1out**. diff --git a/docs/gettingstarted/progressivevpp/routing.rst b/docs/gettingstarted/progressivevpp/routing.rst index c9586c1c85d..38841b744b3 100644 --- a/docs/gettingstarted/progressivevpp/routing.rst +++ b/docs/gettingstarted/progressivevpp/routing.rst @@ -50,10 +50,10 @@ Setup host route $ sudo ip route add 10.10.2.0/24 via 10.10.1.2 $ ip route - default via 10.0.2.2 dev enp0s3 - 10.0.2.0/24 dev enp0s3 proto kernel scope link src 10.0.2.15 - 10.10.1.0/24 dev vpp1host proto kernel scope link src 10.10.1.1 - 10.10.2.0/24 via 10.10.1.2 dev vpp1host + default via 10.0.2.2 dev enp0s3 + 10.0.2.0/24 dev enp0s3 proto kernel scope link src 10.0.2.15 + 10.10.1.0/24 dev vpp1host proto kernel scope link src 10.10.1.1 + 10.10.2.0/24 via 10.10.1.2 dev vpp1host Setup return route on vpp2 --------------------------- diff --git a/docs/gettingstarted/progressivevpp/runningvpp.rst b/docs/gettingstarted/progressivevpp/runningvpp.rst index 19d2f4e9ede..c24d1040ddf 100644 --- a/docs/gettingstarted/progressivevpp/runningvpp.rst +++ b/docs/gettingstarted/progressivevpp/runningvpp.rst @@ -50,7 +50,7 @@ We should now be able to execute the VPP shell and show the version. __/ __/ _ \ (_)__ | | / / _ \/ _ \ _/ _// // / / / _ \ | |/ / ___/ ___/ /_/ /____(_)_/\___/ |___/_/ /_/ - + vpp# show version vpp v18.07-release built by root on c469eba2a593 at Mon Jul 30 23:27:03 UTC 2018 vpp# diff --git a/docs/gettingstarted/progressivevpp/settingupenvironment.rst b/docs/gettingstarted/progressivevpp/settingupenvironment.rst index c012f691e8b..8c67c79b188 100644 --- a/docs/gettingstarted/progressivevpp/settingupenvironment.rst +++ b/docs/gettingstarted/progressivevpp/settingupenvironment.rst @@ -11,8 +11,7 @@ All of these exercises are designed to be performed on an Ubuntu 16.04 (Xenial) Install Virtual Box and Vagrant ------------------------------- -You will need to install Virtual Box and Vagrant. If you have not installed Virtual Box or Vagrant please -refer to :ref:`installingVboxVagrant` to install Virtual Box and Vagrant. +You will need to install Virtual Box and Vagrant. Create a Vagrant Directory --------------------------- @@ -30,17 +29,17 @@ Create a file called **Vagrantfile** with the following contents: # -*- mode: ruby -*- # vi: set ft=ruby : - + Vagrant.configure(2) do |config| - + config.vm.box = "bento/ubuntu-18.04" config.vm.box_check_update = false - + vmcpu=(ENV['VPP_VAGRANT_VMCPU'] || 2) vmram=(ENV['VPP_VAGRANT_VMRAM'] || 4096) - + config.ssh.forward_agent = true - + config.vm.provider "virtualbox" do |vb| vb.customize ["modifyvm", :id, "--ioapic", "on"] vb.memory = "#{vmram}" @@ -129,7 +128,7 @@ Create some startup files We will create some startup files for the use of this tutorial. Typically you will modify the startup.conf file found in /etc/vpp/startup.conf. For more information -on this file refer to :ref:`startup`. +on this file refer to :ref:`configuration_reference`. When running multiple VPP instances, each instance needs to have specified a 'name' or 'prefix'. In the example below, the 'name' or 'prefix' diff --git a/docs/gettingstarted/progressivevpp/switching.rst b/docs/gettingstarted/progressivevpp/switching.rst index a28e860fdaa..7ee559815ec 100644 --- a/docs/gettingstarted/progressivevpp/switching.rst +++ b/docs/gettingstarted/progressivevpp/switching.rst @@ -80,8 +80,8 @@ bridge domain number not in use: .. code-block:: console vpp# show bridge-domain - ID Index Learning U-Forwrd UU-Flood Flooding ARP-Term BVI-Intf - 0 0 off off off off off local0 + ID Index Learning U-Forwrd UU-Flood Flooding ARP-Term BVI-Intf + 0 0 off off off off off local0 In the example above, there is bridge domain ID '0' already. Even though sometimes we might get feedback as below: @@ -175,15 +175,15 @@ Examine l2 fib .. code-block:: console vpp# show l2fib verbose - Mac Address BD Idx Interface Index static filter bvi Mac Age (min) - de:ad:00:00:00:00 1 host-vpp1vpp2 2 0 0 0 disabled - c2:f6:88:31:7b:8e 1 host-vpp1out 1 0 0 0 disabled + Mac Address BD Idx Interface Index static filter bvi Mac Age (min) + de:ad:00:00:00:00 1 host-vpp1vpp2 2 0 0 0 disabled + c2:f6:88:31:7b:8e 1 host-vpp1out 1 0 0 0 disabled 2 l2fib entries .. code-block:: console vpp# show l2fib verbose - Mac Address BD Idx Interface Index static filter bvi Mac Age (min) - de:ad:00:00:00:00 1 loop0 2 1 0 1 disabled - c2:f6:88:31:7b:8e 1 host-vpp2vpp1 1 0 0 0 disabled + Mac Address BD Idx Interface Index static filter bvi Mac Age (min) + de:ad:00:00:00:00 1 loop0 2 1 0 1 disabled + c2:f6:88:31:7b:8e 1 host-vpp2vpp1 1 0 0 0 disabled 2 l2fib entries diff --git a/docs/gettingstarted/progressivevpp/traces.rst b/docs/gettingstarted/progressivevpp/traces.rst index a3408586ee8..d1dfad56a45 100644 --- a/docs/gettingstarted/progressivevpp/traces.rst +++ b/docs/gettingstarted/progressivevpp/traces.rst @@ -2,7 +2,7 @@ .. toctree:: -Using the trace command +Using the trace command ======================== Skills to be Learned @@ -21,26 +21,26 @@ Basic Trace Commands Show trace buffer [max COUNT]. -.. code-block:: console +.. code-block:: console vpp# show trace Clear trace buffer and free memory. -.. code-block:: console +.. code-block:: console vpp# clear trace filter trace output - include NODE COUNT | exclude NODE COUNT | none. -.. code-block:: console +.. code-block:: console vpp# trace filter Add Trace ---------- -.. code-block:: console +.. code-block:: console vpp# trace add af-packet-input 10 @@ -69,7 +69,7 @@ The following list of nodes are supported under trace add: Ping from Host to VPP ---------------------- -.. code-block:: console +.. code-block:: console vpp# q $ ping -c 1 10.10.1.2 @@ -80,10 +80,10 @@ Ping from Host to VPP 1 packets transmitted, 1 received, 0% packet loss, time 0ms rtt min/avg/max/mdev = 0.283/0.283/0.283/0.000 ms -Examine Trace of ping from host to VPP +Examine Trace of ping from host to VPP ---------------------------------------- -.. code-block:: console +.. code-block:: console $ sudo vppctl -s /run/vpp/cli-vpp1.sock vpp# show trace @@ -144,14 +144,14 @@ Examine Trace of ping from host to VPP Clear trace buffer ------------------- -.. code-block:: console +.. code-block:: console vpp# clear trace -Ping from VPP to Host +Ping from VPP to Host ----------------------- -.. code-block:: console +.. code-block:: console vpp# ping 10.10.1.1 64 bytes from 10.10.1.1: icmp_seq=1 ttl=64 time=.0789 ms @@ -167,7 +167,7 @@ Examine Trace of ping from VPP to host The output will demonstrate FD.io VPP's trace of ping for all packets. -.. code-block:: console +.. code-block:: console vpp# show trace ------------------- Start of thread 0 vpp_main ------------------- @@ -465,16 +465,16 @@ After examining the trace, clear it again using vpp# clear trace. Examine ARP table (neighbors) ----------------------------- -.. code-block:: console +.. code-block:: console vpp# show ip neighbors Time IP4 Flags Ethernet Interface - 1101.5636 10.10.1.1 D e2:0f:1e:59:ec:f7 host-vpp1out + 1101.5636 10.10.1.1 D e2:0f:1e:59:ec:f7 host-vpp1out Examine routing tables ----------------------- -.. code-block:: console +.. code-block:: console vpp# show ip fib ipv4-VRF:0, fib_index:0, flow hash:[src dst sport dport proto ] locks:[src:plugin-hi:2, src:adjacency:1, src:default-route:1, ] diff --git a/docs/gettingstarted/progressivevpp/twovppinstances.rst b/docs/gettingstarted/progressivevpp/twovppinstances.rst index c6a7420fcc8..eadd4e62b12 100644 --- a/docs/gettingstarted/progressivevpp/twovppinstances.rst +++ b/docs/gettingstarted/progressivevpp/twovppinstances.rst @@ -64,7 +64,7 @@ Run a second FD.io VPP instance named: vpp2. __/ __/ _ \ (_)__ | | / / _ \/ _ \ _/ _// // / / / _ \ | |/ / ___/ ___/ /_/ /____(_)_/\___/ |___/_/ /_/ - + vpp# show version vpp v18.07-release built by root on c469eba2a593 at Mon Jul 30 23:27:03 UTC 2018 vpp# quit @@ -121,7 +121,7 @@ Ping 10.10.2.2 from vpp1 .. code-block:: console - $ ping 10.10.2.2 + $ ping 10.10.2.2 Ping 10.10.2.1 from vpp2 -- cgit 1.2.3-korg