docs: Incororate Scott's overall review
Change-Id: Ic70a62e17891fa9291a5274400ae89f1d6194b6e
Signed-off-by: John DeNisco <jdenisco@cisco.com>
diff --git a/docs/_images/vhost-topo.png b/docs/_images/vhost-topo.png
index c2baf7e..6da458d 100644
--- a/docs/_images/vhost-topo.png
+++ b/docs/_images/vhost-topo.png
Binary files differ
diff --git a/docs/gettingstarted/developers/index.rst b/docs/gettingstarted/developers/index.rst
index cccb18d..165488c 100644
--- a/docs/gettingstarted/developers/index.rst
+++ b/docs/gettingstarted/developers/index.rst
@@ -4,6 +4,14 @@
Developers
##########
+The Developers section covers the following areas:
+
+* Building VPP
+* Describes the components of the four VPP layers
+* How to Create, Add, Enable/Disable features
+* Discusses different aspects of Bounded-index Extensible Hashing (bihash)
+
+
.. toctree::
:maxdepth: 2
diff --git a/docs/gettingstarted/index.rst b/docs/gettingstarted/index.rst
index 754796b..acee196 100644
--- a/docs/gettingstarted/index.rst
+++ b/docs/gettingstarted/index.rst
@@ -1,8 +1,31 @@
.. _gettingstarted:
-###############
-Getting Started
-###############
+######################
+Getting Started Guides
+######################
+
+The Getting Started Guide is comprised of several different sections; a section for Users, another for Developers, and a section for Writing VPP documentation.
+
+The Users section covers basic VPP installation and configuration operations. This section covers the following areas:
+
+* Describes the different types of VPP packages
+* Describes how to install VPP Binaries on different OS platforms (Ubuntu, Centos, openSUSE).
+* Explains how to configure, then use VPP.
+* Explains how to use the Configuration Utility.
+
+The Developers section covers the following areas:
+
+* Building VPP
+* Describes the components of the four VPP layers
+* How to Create, Add, Enable/Disable features
+* Discusses different aspects of Bounded-index Extensible Hashing (bihash)
+
+The Writing VPP Documentation section covers the following topics:
+
+* How to build VPP documents
+* How to push your changes to the VPP Docs Repository
+* Identifies the different styles associated to reStructuredText
+* Identifies the different styles associated to Markdown
.. toctree::
:maxdepth: 2
diff --git a/docs/gettingstarted/users/configuring/hugepages.rst b/docs/gettingstarted/users/configuring/hugepages.rst
index 42f6aa3..76ac7d0 100644
--- a/docs/gettingstarted/users/configuring/hugepages.rst
+++ b/docs/gettingstarted/users/configuring/hugepages.rst
@@ -3,11 +3,12 @@
Huge Pages
----------
-VPP requires *'hugepages'* to run. VPP will overwrite existing hugepage
-settings when VPP is installed. By default, VPP sets the number of hugepages on
-a system to 1024 2M hugepages (1G hugepages are no longer supported). This is
-the number of hugepages on the system, not just used by VPP. When VPP is
-installed, the following file is copied to the system and used to apply the
+VPP requires *'hugepages'* to run. VPP will overwrite existing hugepage settings
+when VPP is installed. By default, VPP sets the number of hugepages on a system
+to 1024 2M hugepages (1G hugepages are no longer supported). This is the number
+of hugepages on the system, not just used by VPP.
+
+When VPP is installed, the following file is copied to the system and used to apply the
hugepage settings on VPP installation and system reboot:
.. code-block:: console
diff --git a/docs/gettingstarted/users/configuring/index.rst b/docs/gettingstarted/users/configuring/index.rst
index 75c5276..f1244c6 100644
--- a/docs/gettingstarted/users/configuring/index.rst
+++ b/docs/gettingstarted/users/configuring/index.rst
@@ -1,10 +1,10 @@
.. _configuring:
Configuring VPP
-===============
+==================
-There is some basic configuration that is need to run FD.io VPP. This section
-will describe some basic configuration.
+There is some basic configuration that is needed to run FD.io VPP. This section
+describes the basic configuration:
.. toctree::
:maxdepth: 2
diff --git a/docs/gettingstarted/users/configuring/startup.rst b/docs/gettingstarted/users/configuring/startup.rst
index 7dd2c99..8ce27eb 100644
--- a/docs/gettingstarted/users/configuring/startup.rst
+++ b/docs/gettingstarted/users/configuring/startup.rst
@@ -10,9 +10,10 @@
After a successful installation, VPP installs a startup config file named
-*'startup.conf'* in the *'/etc/vpp/'*' directory. This file can be tailored to
+*startup.conf* in the */etc/vpp/* directory. This file can be tailored to
make VPP run as desired, but contains default values for typical installations.
-Below are more details about this file and parameter and values it contains.
+
+Below are more details about this file and the parameters and values it contains.
Introduction
------------
diff --git a/docs/gettingstarted/users/configutil/commandfour.rst b/docs/gettingstarted/users/configutil/commandfour.rst
index 27cac82..6a1b82e 100644
--- a/docs/gettingstarted/users/configutil/commandfour.rst
+++ b/docs/gettingstarted/users/configutil/commandfour.rst
@@ -4,11 +4,11 @@
List/Install/Uninstall VPP
**************************
-With option "4" the user can list, install or uninstall the FD.io VPP packages. If there
-are packages already installed, the packages will be listed and then the user will be asked
-if the packages should be uninstalled. If no packages are installed the user will be asked if
-the FD.io packages should be installed. The packages installed will be the latest released
-packages.
+With command option "4" the user can list, install, or uninstall the FD.io VPP
+packages. If there are packages already installed, then the packages will be listed
+and the user will be asked if the packages should be uninstalled. If no packages are
+installed, then the user will be asked if the FD.io packages should be installed. The
+packages installed will be the latest released packages.
Uninstalling the packages:
diff --git a/docs/gettingstarted/users/configutil/commandone.rst b/docs/gettingstarted/users/configutil/commandone.rst
index 9d63809..33b6dbb 100644
--- a/docs/gettingstarted/users/configutil/commandone.rst
+++ b/docs/gettingstarted/users/configutil/commandone.rst
@@ -4,9 +4,9 @@
Show System Information
***********************
-With option "1" the user can inspect the system characteristics.
+With command option "1" the user can inspect the system characteristics.
-This example shows a system that VPP has not yet been installed.
+This example shows a system that has not yet had VPP installed.
.. code-block:: console
diff --git a/docs/gettingstarted/users/configutil/commandthree.rst b/docs/gettingstarted/users/configutil/commandthree.rst
index c4c4429..589a367 100644
--- a/docs/gettingstarted/users/configutil/commandthree.rst
+++ b/docs/gettingstarted/users/configutil/commandthree.rst
@@ -1,13 +1,14 @@
.. _config-command-three:
-***********************
+************************
Apply the Configuration
-***********************
+************************
-After the configuration files have been examined and are correct. The configuration
-can be applied. After the configuration is applied use option "1" to check the
-system configuration. Notice the default is NOT to change the grub file. If the option
-to change the grub command line is selected a reboot of the system will be required.
+After the configuration files have been examined and verified as correct, then the
+configuration can be applied by using command option '3'. After the configuration
+is applied, use option "1" to check the system configuration. Notice the default is
+NOT to change the grub file. If the option to change the grub command line is selected,
+then a reboot of the system will be required.
.. code-block:: console
diff --git a/docs/gettingstarted/users/configutil/commandtwo.rst b/docs/gettingstarted/users/configutil/commandtwo.rst
index 0d06c14..c30663f 100644
--- a/docs/gettingstarted/users/configutil/commandtwo.rst
+++ b/docs/gettingstarted/users/configutil/commandtwo.rst
@@ -4,10 +4,12 @@
Dry Run
*******
-With the config utility dry run option the important configuration files are created
-so that the user can examine them and then if they look reasonable apply them with
-option 3. The files for **Ubuntu** can be found in the root directory /usr/local/vpp/vpp-config/dryrun
-and for **Centos** in /usr/vpp/vpp-config/dryrun.
+With command option '2' (the config utility *dry run* option) the important
+configuration files are created so that the user can examine them, and then
+if they look reasonable apply them with command option 3.
+
+The files for **Ubuntu** can be found in the root directory */usr/local/vpp/vpp-config/dryrun*
+and for **Centos** in directory */usr/vpp/vpp-config/dryrun*.
The important configuration files are **/etc/vpp/startup.conf**, **/etc/sysctl.d/80-vpp.conf**,
and **/etc/default/grub**
@@ -15,32 +17,32 @@
Startup.conf
============
-FD.io VPP startup parameters are configured in the file **/etc/vpp/startup.conf**. The
-utility creates this file under the vpp-config root directory in vpp/startup.conf.
-the values in this file come from the questions asked about the devices, cores, rx queues,
+FD.io VPP startup parameters are configured in the file **/etc/vpp/startup.conf**.
+The utility creates this file under the *vpp-config* root directory in the file *vpp/startup.conf*.
+The values in this file come from the questions asked about the devices, cores, rx queues,
and tcp parameters.
80-vpp.conf
-===========
+============
The huge page configuration comes by setting values in the file **/etc/sysctl.d/80-vpp.conf**.
-The utility creates the file under the root directory in sysctl.d/80-vpp.conf. When asked the
-question about huge pages the correct values are put in the dryrin file.
+The utility creates the file under the root directory in the file *sysctl.d/80-vpp.conf*. When asked the
+question about huge pages the correct values are put in the dryrun file.
grub
====
-CPUs can be isolated for use by VPP or other processes such as VMs using the grub configuration
-file. This file is **/etc/default/grub**. This file must be modified with care. It is possible to
-make your system unusable if this file is modified incorrectly. The dry run file is located under
-the vpp-config root directory and then default.
+CPUs can be isolated for use by VPP or other processes such as VMs using the grub
+configuration file. This file is **/etc/default/grub**. This file must be modified with
+care. It is possible to make your system unusable if this file is modified incorrectly.
+The dry run file is located under the *vpp-config* root directory and then default.
-*********************
+***********************
Executing the Dry Run
-*********************
+***********************
-The following is an example of how to execute a dry run. Defaults should be picked first and then
-the values increased accordingly.
+The following is an example of how to execute a dry run. Defaults should be picked first,
+and then the values increased accordingly.
.. code-block:: console
diff --git a/docs/gettingstarted/users/configutil/usingvppconfig.rst b/docs/gettingstarted/users/configutil/usingvppconfig.rst
index 4f1ce6c..8694a83 100644
--- a/docs/gettingstarted/users/configutil/usingvppconfig.rst
+++ b/docs/gettingstarted/users/configutil/usingvppconfig.rst
@@ -8,14 +8,15 @@
user to configure ports, some performance characteristics, the number of huge pages
and install/uninstall the released FD.io packages.
-It is recommended that the menu options are executed in this order.
+It is recommended that the menu command options, noted below as *"x)"*, are run in
+this order (command option 4 first, then options 1,2,3):
#. :ref:`4) List/Install/Uninstall VPP <config-command-four>`
#. :ref:`1) Show basic system information <config-command-one>`
#. :ref:`2) Dry Run <config-command-two>`
#. :ref:`3) Full Configuration <config-command-three>`
-Once vpp-config is installed as a root user execute the following
+Once vpp-config is installed as a root user, then run the following code:
.. code-block:: console
@@ -44,8 +45,8 @@
Default Values
==============
-If you do not choose to modify the default for any of the questions prompted by vpp-config,
-you may press the ENTER key to select the default options:
+If you do not choose to modify the default for any of the questions prompted by vpp-config, then
+you may press the **ENTER** key to select the default options:
* Questions that ask [Y/n], the capital letter Y is the default answer.
* Numbers have their default within brackets, such as in [1024], the 1024 is the default.
diff --git a/docs/gettingstarted/users/index.rst b/docs/gettingstarted/users/index.rst
index 6fd7260..36640a8 100644
--- a/docs/gettingstarted/users/index.rst
+++ b/docs/gettingstarted/users/index.rst
@@ -1,8 +1,16 @@
.. _users:
-#####
+########
Users
-#####
+########
+
+The Users section covers basic VPP installation and configuration operations. This
+section covers the following areas:
+
+* Describes the different types of VPP packages
+* Describes how to install VPP Binaries on different OS platforms (Ubuntu, Centos, openSUSE)
+* Explains how to configure, then use VPP
+* Explains how to use the Configuration Utility
.. toctree::
:maxdepth: 2
diff --git a/docs/gettingstarted/users/installing/centos.rst b/docs/gettingstarted/users/installing/centos.rst
index bb69eb9..470ca87 100644
--- a/docs/gettingstarted/users/installing/centos.rst
+++ b/docs/gettingstarted/users/installing/centos.rst
@@ -8,7 +8,7 @@
Update the OS
-------------
-It is probably a good idea to update and upgrade the OS before starting:
+Before starting the repository setup, it is a good idea to first update and upgrade the OS.
.. code-block:: console
diff --git a/docs/gettingstarted/users/installing/index.rst b/docs/gettingstarted/users/installing/index.rst
index 7636ec8..6cadae0 100644
--- a/docs/gettingstarted/users/installing/index.rst
+++ b/docs/gettingstarted/users/installing/index.rst
@@ -3,11 +3,10 @@
.. toctree::
Installing VPP from Packages
-============================
+==============================
-If you are simply using vpp, it can be convenient to install the binaries from
-existing packages. This guide will describe how pull, install and run the VPP
-packages.
+If you want to use VPP it can be convenient to install the binaries from
+existing packages. This guide describes how to pull, install and run the VPP packages.
.. toctree::
@@ -20,10 +19,13 @@
packages
Installing VPP Binaries
------------------------
+----------------------------------
+
+This section provides directions on how to Install VPP binaries on Ubuntu, Centos,
+and openSUSE platforms.
Installing on Ubuntu
-^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^
The following are instructions on how to install VPP on Ubuntu.
.. toctree::
diff --git a/docs/gettingstarted/users/installing/opensuse.rst b/docs/gettingstarted/users/installing/opensuse.rst
index 8e91ebd..b5dcbc3 100644
--- a/docs/gettingstarted/users/installing/opensuse.rst
+++ b/docs/gettingstarted/users/installing/opensuse.rst
@@ -4,17 +4,18 @@
Installing
==========
-Top install VPP on openSUSE first pick the following release and execute the appropriate commands.
+To install VPP on openSUSE, first install the following release and then execute
+the appropriate commands.
openSUSE Tumbleweed (rolling release)
--------------------------------------
+------------------------------------------------------------
.. code-block:: console
sudo zypper install vpp vpp-plugins
openSUSE Leap 42.3
-------------------
+--------------------------------
.. code-block:: console
diff --git a/docs/gettingstarted/users/installing/packages.rst b/docs/gettingstarted/users/installing/packages.rst
index d67ff60..55ddf05 100644
--- a/docs/gettingstarted/users/installing/packages.rst
+++ b/docs/gettingstarted/users/installing/packages.rst
@@ -1,7 +1,9 @@
.. _packages:
Packages
-========
+==========
+
+This section identifies the different VPP packages and describes their contents.
.. toctree::
diff --git a/docs/gettingstarted/users/installing/ubuntu.rst b/docs/gettingstarted/users/installing/ubuntu.rst
index 9c082e6..5b4a1d8 100644
--- a/docs/gettingstarted/users/installing/ubuntu.rst
+++ b/docs/gettingstarted/users/installing/ubuntu.rst
@@ -3,13 +3,13 @@
.. toctree::
Ubuntu 16.04 - Setup the fd.io Repository
-=========================================
+==========================================
-From the following choose one of the releases to install.
+From the following, choose one of the releases to install.
Update the OS
--------------
+-----------------------
It is probably a good idea to update and upgrade the OS before starting
@@ -19,7 +19,7 @@
Point to the Repository
------------------------
+-----------------------------------
Create a file **"/etc/apt/sources.list.d/99fd.io.list"** with the contents that point to
the version needed. The contents needed are shown below.
@@ -27,7 +27,7 @@
.. _install_vpp:
VPP latest Release
-^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^
Create the file **/etc/apt/sources.list.d/99fd.io.list** with contents:
@@ -37,7 +37,7 @@
VPP stable/1804 Branch
-^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^
Create the file **/etc/apt/sources.list.d/99fd.io.list** with contents:
@@ -47,7 +47,7 @@
VPP master Branch
-^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^
Create the file **/etc/apt/sources.list.d/99fd.io.list** with contents:
@@ -57,7 +57,7 @@
Install the Mandatory Packages
-==============================
+===============================
.. code-block:: console
@@ -66,7 +66,7 @@
Install the Optional Packages
-=============================
+==============================
.. code-block:: console
diff --git a/docs/gettingstarted/writingdocs/index.rst b/docs/gettingstarted/writingdocs/index.rst
index e1ce767..1361c42 100644
--- a/docs/gettingstarted/writingdocs/index.rst
+++ b/docs/gettingstarted/writingdocs/index.rst
@@ -4,6 +4,15 @@
Writing VPP Documentation
#########################
+This section covers the following topics:
+
+* Building VPP Documents
+* Merging FD.io VPP documents and performing a Git review
+* Using Read the Docs
+* reStructured Text Style Guide that describes different format styles
+* Markdown Style Guide that describes different format styles
+
+
.. toctree::
buildingrst
@@ -13,6 +22,3 @@
styleguidemd/index.rst
todo
pushingapatch
-
-
-
diff --git a/docs/overview/index.rst b/docs/overview/index.rst
index d3da0e2..8d1e434 100644
--- a/docs/overview/index.rst
+++ b/docs/overview/index.rst
@@ -1,8 +1,14 @@
.. _overview:
-=========================================
+==========
Overview
-=========================================
+==========
+
+This section discusses the following information:
+
+* What VPP is, what packet processing provides and the benefits VPP provides
+
+
.. toctree::
:maxdepth: 1
diff --git a/docs/overview/whatisvpp/dataplane.rst b/docs/overview/whatisvpp/dataplane.rst
index 9113038..256165f 100644
--- a/docs/overview/whatisvpp/dataplane.rst
+++ b/docs/overview/whatisvpp/dataplane.rst
@@ -1,8 +1,10 @@
.. _packet-processing:
-=================
+===================
Packet Processing
-=================
+===================
+
+This section identifies different components of packet processing and describes their benefits:
* Layer 2 - 4 Network Stack
diff --git a/docs/overview/whatisvpp/developer.rst b/docs/overview/whatisvpp/developer.rst
index a0bb2d4..57000d4 100644
--- a/docs/overview/whatisvpp/developer.rst
+++ b/docs/overview/whatisvpp/developer.rst
@@ -4,6 +4,8 @@
Developer Friendly
==================
+This section describes the different ways VPP is friendly to developers:
+
* Extensive runtime counters; throughput, `intructions per cycle <https://en.wikipedia.org/wiki/Instructions_per_cycle>`_, errors, events etc.
* Integrated pipeline tracing facilities
* Multi-language API bindings
diff --git a/docs/overview/whatisvpp/fast.rst b/docs/overview/whatisvpp/fast.rst
index b04c12f..9e9e314 100644
--- a/docs/overview/whatisvpp/fast.rst
+++ b/docs/overview/whatisvpp/fast.rst
@@ -4,7 +4,9 @@
Fast, Scalable and Deterministic
================================
-* `Continuous integration and system testing <https://wiki.fd.io/view/CSIT#Start_Here>`_
+This section describes the ways that VPP is fast, scalable and deterministic:
+
+* `Continuous integration and system testing (CSIT) <https://wiki.fd.io/view/CSIT#Start_Here>`_
* Including continuous & extensive, latency and throughput testing
