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:
*******************************
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

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

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

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

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

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

@ -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/>`_.
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`_.
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,8 +20,13 @@ 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:
@ -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.

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

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

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
gettingstarted/index
links/index
usecases/index
troubleshooting/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
=================
**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
________

7
docs/reference/index.rst
View File

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

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

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