ligang/vpp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

DOCS: Cleanup Getting Started

Browse Source 
Change-Id: I4766773779f8d5c30a24bfed48090d7305c80ec5
Signed-off-by: John DeNisco <jdenisco@cisco.com>
This commit is contained in:
John DeNisco
2018-08-13 17:00:06 -04:00
parent 34eb5d423d
commit 758dc46072
11 changed files with 97 additions and 253 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/gettingstarted/writingdocs/gitreview.rst → docs/gettingstarted/developers/gitreview.rst
View File

@ -1,10 +1,10 @@
.. _gitreview: .. _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 Setup
======== ========
@ -77,12 +77,13 @@ Make sure you have modified the correct files with:
$ git status $ git status
$ git diff $ 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 .. code-block:: console
$ git add <filename> $ git add <filename>
$ git commit -s -m "DOCS: <COMMIT_MESSAGE>" $ git commit -s -m "<*TAG*>: <*COMMIT_MESSAGE*>"
$ git review $ git review
If you are creating a draft, meaning you do not want your changes reviewed yet, do the following: 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. 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: 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 reset --hard origin/master
$ git checkout 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

1
docs/gettingstarted/developers/index.rst
View File

@ -18,6 +18,7 @@ The Developers section covers the following areas:
building building
running_vpp running_vpp
gdb_examples gdb_examples
gitreview
softwarearchitecture softwarearchitecture
infrastructure infrastructure
vlib vlib

7
docs/gettingstarted/developers/running_vpp.rst
View File

@ -20,6 +20,13 @@ Running the release image:
# make run-release # make run-release
# #
Running the debug image:
.. code-block:: console
# make run
#
With GDB With GDB
_________________________ _________________________

199
docs/gettingstarted/writingdocs/buildingrst.rst
View File

@ -1,32 +1,18 @@
.. _buildingrst: .. _buildingrst:
********************** **************************
Building VPP Documents Creating VPP Documents
********************** **************************
Overview
========
These instructions show how the VPP documentation sources are built. 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/>`_. The VPP Documents are written using `reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ (rst),
We will also cover how to view your build on Read the Docs in `Using Read the Docs`_. or markdown (md). These files are then built using the Sphinx build system `Sphinx <http://www.sphinx-doc.org/en/master/>`_.
Get the VPP sources
=====================
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`_. Start with a clone of the vpp repository.
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.
.. code-block:: console .. code-block:: console
@ -34,8 +20,13 @@ For example start with a clone of the vpp-docs.
$ cd vpp $ 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: In the vpp root directory on your system, run:
@ -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. interfere with other builds that may use different versions of software.
Build the html files 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** 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: 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 $ make html
View the results View the results
^^^^^^^^^^^^^^^^ =================
| If there are no errors during the build process, you should now have an **index.html** file in your | 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. | **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 $ deactivate
Getting your documents reviewed and merged
==========================================
Install Sphinx manually VPP documents are reviewed and merged like and other source code. Refer to :ref:`gitreview`
_______________________ to get your changes reviewed and merged.
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

9
docs/gettingstarted/writingdocs/index.rst
View File

@ -1,25 +1,20 @@
.. _writingdocs: .. _writingdocs:
######################### #########################
Writing VPP Documentation VPP Documents
######################### #########################
This section covers the following topics: This section covers the following topics:
* Building VPP Documents * Building VPP Documents
* Merging FD.io VPP documents and performing a Git review * Merging FD.io VPP documents and performing a Git review
* Using Read the Docs
* reStructured Text Style Guide that describes different format styles * reStructured Text Style Guide that describes different format styles
* Markdown Style Guide that describes different format styles * Markdown Style Guide that describes different format styles
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 3
buildingrst buildingrst
gitreview
readthedocs
styleguide/index.rst styleguide/index.rst
styleguidemd/index.rst styleguidemd/index.rst
todo
pushingapatch

55
docs/gettingstarted/writingdocs/todo.rst
View File

@ -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.

1
docs/index.rst
View File

@ -23,6 +23,7 @@ Finally it is useful both a software development kit or an appliance out of the
overview/index overview/index
gettingstarted/index gettingstarted/index
links/index
usecases/index usecases/index
troubleshooting/index troubleshooting/index
guides/index guides/index

33
docs/links/index.rst Normal file
View File

@ -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/>`_

6
docs/gettingstarted/writingdocs/pushingapatch.rst → docs/reference/github/index.rst
View File

@ -4,9 +4,9 @@
Github Repository Github Repository
================= =================
**The github repository is no longer being used. The gerrit server is being used.** **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.**
To use the gerrit repository refer to :ref:`gitreview`. **It should only be used by a document developer.**
Overview Overview
________ ________

7
docs/reference/index.rst
View File

@ -1,12 +1,15 @@
.. _reference: .. _reference:
######################
Reference Reference
========= ######################
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
readthedocs/index.rst
github/index.rst
vppvagrant/index.rst vppvagrant/index.rst
cmdreference/index.rst
buildsystem/index.rst buildsystem/index.rst
multiarch/index.rst multiarch/index.rst
cmdreference/index.rst

5
docs/gettingstarted/writingdocs/readthedocs.rst → docs/reference/readthedocs/index.rst
View File

@ -1,8 +1,7 @@
.. _readthedocs: .. _readthedocs:
******************* Read The Docs
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. `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.