DOCS: Cleanup Getting Started

Change-Id: I4766773779f8d5c30a24bfed48090d7305c80ec5
Signed-off-by: John DeNisco <jdenisco@cisco.com>

11 files changed, 97 insertions, 253 deletions

diff --git a/docs/gettingstarted/writingdocs/gitreview.rst b/docs/gettingstarted/developers/gitreview.rst
index 146b06f5c00..f727fb16756 100644
--- a/docs/gettingstarted/writingdocs/gitreview.rst
+++ b/docs/gettingstarted/developers/gitreview.rst
@@ -1,10 +1,10 @@
 .. _gitreview:
 
 *******************************
-Merging FD.io VPP documents
+Getting a Patch Reviewed
 *******************************
 
-This section describes how to get FD.io VPP documents reviewed and merged.
+This section describes how to get FD.io VPP sources reviewed and merged.
 
 Setup
 ========
@@ -77,12 +77,13 @@ Make sure you have modified the correct files with:
     $ git status
     $ git diff
 
-Then add and commit the patch. For documents we will add a tag **DOCS:**
+Then add and commit the patch. You may want to add a tag to the commit comments.
+For example for document only patches you should add the tag **DOCS:**.
 
 .. code-block:: console
 
     $ git add <filename>
-    $ git commit -s -m "DOCS: <COMMIT_MESSAGE>"
+    $ git commit -s -m "<*TAG*>: <*COMMIT_MESSAGE*>"
     $ git review
 
 If you are creating a draft, meaning you do not want your changes reviewed yet, do the following:
@@ -102,7 +103,7 @@ Existing patch
 
 The "change number" used below is in the URL of the review.
 
-After clicking an individual review, the change number can be found in the URL at "https://gerrit.fd.io/r/#/c/<CHANGE_NUMBER>/"
+After clicking an individual review, the change number can be found in the URL at "https://gerrit.fd.io/r/#/c/<*CHANGE_NUMBER*>/"
 
 To view an existing patch:
 
@@ -138,3 +139,19 @@ When you're done viewing or modifying a branch, get back to the master branch wi
 
     $ git reset --hard origin/master
     $ git checkout master
+
+Resolving a Conflict
+--------------------------------
+
+If a change has a conflict it should be resolved with the following:git-review -d <Gerrit change #>
+
+.. code-block:: console
+
+    $ git rebase origin/master
+       while (conflicts)
+          <fix conflicts>
+          $ git rebase --continue
+    $ git review
+
+
+
diff --git a/docs/gettingstarted/developers/index.rst b/docs/gettingstarted/developers/index.rst
index 661567fcb67..76feb057552 100644
--- a/docs/gettingstarted/developers/index.rst
+++ b/docs/gettingstarted/developers/index.rst
@@ -18,6 +18,7 @@ The Developers section covers the following areas:
    building
    running_vpp
    gdb_examples
+   gitreview
    softwarearchitecture
    infrastructure
    vlib
diff --git a/docs/gettingstarted/developers/running_vpp.rst b/docs/gettingstarted/developers/running_vpp.rst
index 4c717af3e19..f0d56fbab2b 100644
--- a/docs/gettingstarted/developers/running_vpp.rst
+++ b/docs/gettingstarted/developers/running_vpp.rst
@@ -20,6 +20,13 @@ Running the release image:
    # make run-release
    #
 
+Running the debug image:
+
+.. code-block:: console
+
+   # make run
+   #
+
 With GDB
 _________________________
 
diff --git a/docs/gettingstarted/writingdocs/buildingrst.rst b/docs/gettingstarted/writingdocs/buildingrst.rst
index 10d073bdc60..5134bb395ee 100644
--- a/docs/gettingstarted/writingdocs/buildingrst.rst
+++ b/docs/gettingstarted/writingdocs/buildingrst.rst
@@ -1,32 +1,18 @@
 .. _buildingrst:
 
-**********************
-Building VPP Documents
-**********************
-
-Overview
-========
+**************************
+Creating VPP Documents
+**************************
 
 These instructions show how the VPP documentation sources are built.
 
-FD.io VPP Documentation uses `reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ (rst) files, which are used by `Sphinx <http://www.sphinx-doc.org/en/master/>`_.
-We will also cover how to view your build on Read the Docs in `Using Read the Docs`_.
-
+The VPP Documents are written using `reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ (rst),
+or markdown (md). These files are then built using the Sphinx build system `Sphinx <http://www.sphinx-doc.org/en/master/>`_.
 
-To build your files, you can either `Create a Virtual Environment using virtualenv`_, which installs all the required applications for you,  or you can `Install Sphinx manually`_.
+Get the VPP sources
+=====================
 
-Create a Virtual Environment using virtualenv
-_____________________________________________
-
-For more information on how to use the Python virtual environment check out
-`Installing packages using pip and virtualenv`_.
-
-.. _`Installing packages using pip and virtualenv`: https://packaging.python.org/guides/installing-using-pip-and-virtualenv/
-
-Get the Documents
-^^^^^^^^^^^^^^^^^
-
-For example start with a clone of the vpp-docs.
+Start with a clone of the vpp repository.
 
 .. code-block:: console
 
@@ -34,9 +20,14 @@ For example start with a clone of the vpp-docs.
    $ cd vpp
 
 
-Install the virtual environment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Create a Virtual Environment using virtualenv
+===============================================
  
+For more information on how to use the Python virtual environment check out
+`Installing packages using pip and virtualenv`_.
+
+.. _`Installing packages using pip and virtualenv`: https://packaging.python.org/guides/installing-using-pip-and-virtualenv/
+
 In the vpp root directory on your system, run: 
 
 .. code-block:: console
@@ -51,7 +42,7 @@ Which installs all the required applications into it's own, isolated, virtual en
 interfere with other builds that may use different versions of software.
 
 Build the html files
-^^^^^^^^^^^^^^^^^^^^
+======================
 
 Be sure you are in your vpp-docs/docs directory, since that is where Sphinx will look for your **conf.py**
 file, and build the **.rst** files into an **index.html** file: 
@@ -61,7 +52,7 @@ file, and build the **.rst** files into an **index.html** file:
    $ make html
 
 View the results
-^^^^^^^^^^^^^^^^
+=================
 
 | If there are no errors during the build process, you should now have an **index.html** file in your
 | **vpp/docs/_build/html** directory, which you can then view in your browser.
@@ -81,156 +72,8 @@ Whenever you make changes to your **.rst** files that you want to see, repeat th
 
    $ deactivate
 
+Getting your documents reviewed and merged
+==========================================
 
-Install Sphinx manually
-_______________________
-
-Skip this step if you created a *virtualenv* in the previous step. If you dont want to create a *virtualenv*, you should install Sphinx `here <http://www.sphinx-doc.org/en/master/usage/installation.html>`_, and follow their `getting started guide <http://www.sphinx-doc.org/en/master/usage/quickstart.html>`_.
-
-Building these files will generate an **index.html** file, which you can then view in your browser to verify and see your file changes.
-
-
-To *build* your files, make sure you're in your **vpp-docs/docs** directory, where your **conf.py** file is located, and run:
-
-.. code-block:: console
-
-   $ make html
-
-
-| If there are no errors during the build process, you should now have an **index.html** file in your
-| **vpp-docs/docs/_build/html** directory, which you can then view in your browser.
-
-.. figure:: /_images/htmlBuild.png
-   :scale: 35%
-   :align: center
-
-Whenever you make changes to your **.rst** files that you want to see, repeat this build process.
-
-
-Using Read the Docs
-___________________
-
-`Read the Docs <https://readthedocs.org/>`_ is a website that "simplifies software documentation by automating building, versioning, and hosting of your docs for you". Essentially, it accesses your Github repo to generate the **index.html** file, and then displays it on its own *Read the Docs* webpage so others can view your documentation. 
-
-Create an account on *Read the Docs* if you haven't already.
-
-Go to your `dashboard <https://readthedocs.org/dashboard/>`_ , and click on "Import a Project".
-
-.. figure:: /_images/importReadDocs.png
-   :scale: 35%
-   :align: left
-
-   This will bring you to a page where you can choose to import a repo from your Github account (only if you've linked your Github account to your Read the Docs account), or to import a repo manually. In this example, we'll do it manually. Click "Import Manually".
-
-|
-|
-|
-|
-|
-|
-|
-
-
-
-This will bring you to a page that asks for your repo details. Set "Name" to your forked repo name, or whatever you want. Set "Repository URL" to the URL of your forked repo (https://github.com/YOURUSERNAME/vpp-docs). "Repository type" should already be selected to "Git". Then click "Next".
-
-
-.. figure:: /_images/importRTDManually.png
-   :scale: 35%
-   :align: left
-
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-
-
-This will bring you to a project page of your repo on Read the Docs. You can confirm it's the correct repo by checking on the right side of the page the Repository URL.
-
-Then click on "Build Version".
-
-.. figure:: /_images/buildVerRTD.png
-   :scale: 35%
-   :align: left
-
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-
-Which takes you to another page showing your recent builds. 
-
-Then click on "Build Version:". This should "Trigger" a build. After about a minute or so you can refresh the page and see that your build "Passed". 
-
-
-.. figure:: /_images/passedBuild.png
-   :scale: 35%
-   :align: left
-
-
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-|
-
-
-Now on your builds page from the previous image, you can click "View Docs" at the top-right, which will take you a *readthedocs.io* page of your generated build!
-
-.. figure:: /_images/rtdWebpage.png
-   :scale: 30%
-   :align: left
+VPP documents are reviewed and merged like and other source code. Refer to :ref:`gitreview`
+to get your changes reviewed and merged.
diff --git a/docs/gettingstarted/writingdocs/index.rst b/docs/gettingstarted/writingdocs/index.rst
index 89245ef28d1..c59a39d0e5d 100644
--- a/docs/gettingstarted/writingdocs/index.rst
+++ b/docs/gettingstarted/writingdocs/index.rst
@@ -1,25 +1,20 @@
 .. _writingdocs:
 
 #########################
-Writing VPP Documentation
+VPP Documents
 #########################
 
 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::
-   :maxdepth: 2
+   :maxdepth: 3
 
    buildingrst
-   gitreview
-   readthedocs
    styleguide/index.rst
    styleguidemd/index.rst
-   todo
-   pushingapatch
diff --git a/docs/gettingstarted/writingdocs/todo.rst b/docs/gettingstarted/writingdocs/todo.rst
deleted file mode 100644
index 8051f6d7e07..00000000000
--- a/docs/gettingstarted/writingdocs/todo.rst
+++ /dev/null
@@ -1,55 +0,0 @@
-.. _todo:
-
-*****
-To Do
-*****
-
-This section describes pieces of these documents that need some work.
-
-All Sections
-============
-
-All the sections need to be spell checked.
-
-Checked for guidelines.
-
-:ref:`vhost`
-============
-
-:ref:`vhosttopo`
-----------------
-
-Get a better topology picture.
-
-:ref:`vhost02`
---------------
-
-The XML file refers to an iso image, come up with a procedure to build that image.
-That should work when used with a cloud image. It should also be mentioned where
-to get a cloud image.
-
-It is mentioned that a queue size of 256 is not large enough. Come up wit a procedure
-to change the queue size.
-
-
-:ref:`users`
-============
-
-The getting started users guide needs an overview
-
-:ref:`cmdreference`
-===================
-
-This section should be references to the doxygen links. The doxygen links will need to be cleaned up.
-This section could be a quick reference only using commands we have tested.
-
-:ref:`vswitchrtr`
-=================
-
-Needs some instructions or be removed.
-
-:ref:`jvppjar`
-==============
-
-Not sure what value this provides.
-
diff --git a/docs/index.rst b/docs/index.rst
index 5a9ddc3288f..ae9276f4b4e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -23,6 +23,7 @@ Finally it is useful both a software development kit or an appliance out of the
 
    overview/index
    gettingstarted/index
+   links/index
    usecases/index
    troubleshooting/index
    guides/index
diff --git a/docs/links/index.rst b/docs/links/index.rst
new file mode 100644
index 00000000000..03b317f0bea
--- /dev/null
+++ b/docs/links/index.rst
@@ -0,0 +1,33 @@
+.. _links:
+
+#############
+Other Links
+#############
+
+There are several places to find helpful Information regarding FD.io VPP.
+
+.. toctree::
+
+FD.io Main Site
+===============
+
+VPP is part of the FD.io Linux Foundation project. The link describing the FD.io Linux
+foundation project is here:
+
+`FD.io Main Site <https://fd.io>`_
+
+VPP Wiki
+==========
+
+Much of the VPP developer documentation can be found on the VPP wiki.
+
+`FD.io VPP wiki <https://wiki.fd.io/view/VPP>`_
+
+Source code Documents
+=====================
+
+Some of VPP is documented in the sources with Doxygen. The links to these documents
+can be found here.
+
+`Doxygen <https://docs.fd.io/vpp/18.10/>`_
+
diff --git a/docs/gettingstarted/writingdocs/pushingapatch.rst b/docs/reference/github/index.rst
index d0d5ec23888..1d7231a9ba4 100644
--- a/docs/gettingstarted/writingdocs/pushingapatch.rst
+++ b/docs/reference/github/index.rst
@@ -4,9 +4,9 @@
 Github Repository
 =================
 
-**The github repository is no longer being used. The gerrit server is being used.**
-
-To use the gerrit repository refer to :ref:`gitreview`.
+**The github repository is only being used as a source for readthedocs.**
+**There should be no reason for the typical developer to use this repository.**
+**It should only be used by a document developer.**
 
 Overview
 ________
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 70a118851ec..48b5170d69c 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -1,12 +1,15 @@
 .. _reference:
 
+######################
 Reference
-=========
+######################
 
 .. toctree::
    :maxdepth: 2
 
+   readthedocs/index.rst
+   github/index.rst
    vppvagrant/index.rst
-   cmdreference/index.rst
    buildsystem/index.rst
    multiarch/index.rst
+   cmdreference/index.rst
diff --git a/docs/gettingstarted/writingdocs/readthedocs.rst b/docs/reference/readthedocs/index.rst
index f97b8d918b6..5ddade8751f 100644
--- a/docs/gettingstarted/writingdocs/readthedocs.rst
+++ b/docs/reference/readthedocs/index.rst
@@ -1,8 +1,7 @@
 .. _readthedocs:
 
-*******************
-Using Read the Docs
-*******************
+Read The Docs
+=================
 
 `Read the Docs <https://readthedocs.org/>`_ is a website that "simplifies software documentation by automating building, versioning, and hosting of your docs for you". Essentially, it accesses your Github repo to generate the **index.html** file, and then displays it on its own *Read the Docs* webpage so others can view your documentation.