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

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

140
docs/gettingstarted/writingdocs/gitreview.rst
View File

@ -1,140 +0,0 @@
.. _gitreview:
*******************************
Merging FD.io VPP documents
*******************************
This section describes how to get FD.io VPP documents reviewed and merged.
Setup
========
If you don't have a Linux Foundation ID, `create one here. <https://identity.linuxfoundation.org/>`_
With your Linux Foundation ID credentials sign into `Gerrit Code Review at gerrit.fd.io <https://gerrit.fd.io/r/login/%23%2Fq%2Fstatus%3Aopen>`_
`Install git-review, <https://www.mediawiki.org/wiki/Gerrit/git-review>`_ which is a "command-line tool for Git / Gerrit to submit a change or to fetch an existing one."
If you're on Ubuntu, install keychain:
.. code-block:: console
$ sudo apt-get install keychain
ssh keys
-------------
To get FD.io VPP documents reviewed the VPP repository should be cloned with ssh. You should be logged into Gerrit Code Review as noted above.
Create your public and private ssh key with:
.. code-block:: console
$ ssh-keygen -t rsa
$ keychain
$ cat ~/.ssh/id_rsa.pub
Copy **all** the contents of the public key (id_rsa.pub) output by the above **cat** command. Then go to your `SSH Public keys settings page <https://gerrit.fd.io/r/#/settings/ssh-keys>`_, click **Add Key ...**, paste your public key, and finally click **Add**.
.. _clone-ssh:
Clone with ssh
==============
Clone the repo with:
.. code-block:: console
$ git clone ssh://gerrit.fd.io:29418/vpp
$ cd vpp
This will only work if the name of the user on your system matches your Gerrit username.
Otherwise, clone with:
.. code-block:: console
$ git clone ssh://YOUR_GERRIT_USERNAME@gerrit.fd.io:29418/vpp
$ cd vpp
When attempting to clone the repo it will ask if you want to add the Server Host Key to the list of known hosts. Type **yes** and hit enter.
Git Review
===========
The VPP documents use the gerrit server and git review for submitting and fetching patches.
New patch
-----------------
When working with new patch use the following to get your patch reviewed.
Make sure you have modified the correct files with:
.. code-block:: console
$ git status
$ git diff
Then add and commit the patch. For documents we will add a tag **DOCS:**
.. code-block:: console
$ git add <filename>
$ git commit -s -m "DOCS: <COMMIT_MESSAGE>"
$ git review
If you are creating a draft, meaning you do not want your changes reviewed yet, do the following:
.. code-block:: console
$ git review -D
After submitting a review, reset where the HEAD is pointing to with:
.. code-block:: console
$ git reset --hard origin/master
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>/"
To view an existing patch:
.. code-block:: console
$ git review -d <change number>
$ git status
$ git diff
.. caution::
If you have made changes and do "git review -d <change number>", your current
changes will try to be stashed so that the working tree can change to the review branch
you specified. If you want to make sure you don't lose your changes, clone another Gerrit
repo into a new directory using the cloning steps shown in :ref:`clone-ssh`, and perform
"git review -d <change number>" in this new directory.
To modify an existing patch, make sure you modified the correct files, and apply the patch with:
.. code-block:: console
$ git review -d <change number>
$ git status
$ git diff
$ git add <filename>
$ git commit --amend
$ git review
When you're done viewing or modifying a branch, get back to the master branch with:
.. code-block:: console
$ git reset --hard origin/master
$ git checkout master

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

237
docs/gettingstarted/writingdocs/pushingapatch.rst
View File

@ -1,237 +0,0 @@
.. _pushingapatch:
=================
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`.
Overview
________
This section will cover how to fork your own branch of the `fdioDocs/vpp-docs <https://github.com/fdioDocs/vpp-docs>`_ repository, clone that repo locally to your computer, make changes to it, and how to issue a pull request when you want your changes to be reflected on the main repo.
.. toctree::
Forking your own branch
_______________________
In your browser, navigate to the repo you want to branch off of. In this case, the `fdioDocs/vpp-docs <https://github.com/fdioDocs/vpp-docs>`_ repo. At the top right of the page you should see this:
.. figure:: /_images/ForkButtons.png
:alt: Figure: Repository options on Github
:scale: 50%
:align: right
|
|
|
Click on "Fork", and then a pop-up should appear where you should then click your Github username. Once this is done, it should automatically take you to the Github page where your new branch is located, just like in the image below.
.. figure:: /_images/usernameFork.png
:alt: Figure: Your own branch of the main repo on Github
:scale: 35%
:align: center
Now your **own branch** can be **cloned** to your computer using the URL (https://github.com/YOURUSERNAME/vpp-docs) of the Github page where your branch is located.
Creating a local repository
___________________________
Now that you have your own branch of the main repository on Github, you can store it locally on your computer. In your shell, navigate to the directory where you want to store your branch/repo. Then execute:
.. code-block:: console
$ git clone https://github.com/YOURUSERNAME/vpp-docs
This will create a directory on your computer named **vpp-docs**, the name of the repo.
Now that your branch is on your computer, you can modify and build files however you wish.
If you are not on the master branch, move to it.
.. code-block:: console
$ git checkout master
Keeping your files in sync with the main repo
_____________________________________________
The following talks about remote branches, but keep in mind that there are currently *two* branches, your local "master" branch (on your computer), and your remote "origin or origin/master" branch (the one you created using "Fork" on the Github website).
You can view your *remote* repositories with:
.. code-block:: console
$ git remote -v
At this point, you may only see the remote branch that you cloned from.
.. code-block:: console
Macintosh:docs Andrew$ git remote -v
origin https://github.com/a-olechtchouk/vpp-docs (fetch)
origin https://github.com/a-olechtchouk/vpp-docs (push)
Now you want to create a new remote repository of the main vpp-docs repo (naming it upstream).
.. code-block:: console
$ git remote add upstream https://github.com/fdioDocs/vpp-docs
You can verify that you have added a remote repo using the previous **git remote -v** command.
.. code-block:: console
$ git remote -v
origin https://github.com/a-olechtchouk/vpp-docs (fetch)
origin https://github.com/a-olechtchouk/vpp-docs (push)
upstream https://github.com/fdioDocs/vpp-docs (fetch)
upstream https://github.com/fdioDocs/vpp-docs (push)
If there have been any changes to files in the main repo (hopefully not the same files you were working on!), you want to make sure your local branch is in sync with them.
To do so, fetch any changes that the main repo has made, and then merge them into your local master branch using:
.. code-block:: console
$ git fetch upstream
$ git merge upstream/master
.. note:: **This is optional, so don't do these commands if you just want one local branch!!!**
You may want to have multiple branches, where each branch has its own different features, allowing you to have multiple pull requests out at a time. To create a new local branch:
.. code-block:: shell
$ git checkout -b cleanup-01
$ git branch
* cleanup-01
master
overview
Now you can redo the previous steps for "Keeping your files in sync with the main repo" for your newly created local branch, and then depending on which branch you want to send out a pull reqest for, proceed below.
Pushing to your branch
______________________
Now that your files are in sync, you want to add modified files, commit, and push them from *your local branch* to your *personal remote branch* (not the main fdioDocs repo).
To check the status of your files, run:
.. code-block:: console
$ git status
In the output example below, I deleted gettingsources.rst, made changes to index.rst and pushingapatch.rst, and have created a new file called buildingrst.rst.
.. code-block:: console
Macintosh:docs Andrew$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
deleted: tasks/writingdocs/gettingsources.rst
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: tasks/writingdocs/index.rst
modified: tasks/writingdocs/pushingapatch.rst
Untracked files:
(use "git add <file>..." to include in what will be committed)
tasks/writingdocs/buildingrst.rst
To add files (use **git add -A** to add all modified files):
.. code-block:: console
$ git add FILENAME1 FILENAME2
Commit and push using:
.. code-block:: console
$ git commit -m 'A descriptive commit message for two files.'
Push your changes for the branch where your changes were made
.. code-block:: console
$ git push origin <branch name>
Here, your personal remote branch is "origin" and your local branch is "master".
.. note::
Using **git commit** after adding your files saves a "Snapshot" of them, so it's very hard to lose your work if you *commit often*.
Initiating a pull request (Code review)
_______________________________________
Once you've pushed your changes to your remote branch, go to your remote branch on Github (https://github.com/YOURUSERNAME/vpp-docs), and click on "New pull request".
.. figure:: /_images/issuePullReq.png
:alt: Figure: Your own branch of the main repo on Github
:scale: 35%
:align: center
This will bring you to a "Comparing changes" page. Click "Create new pull request".
.. figure:: /_images/createNewPullReq.png
:scale: 35%
:align: left
|
|
|
Which will open up text fields to add information to your pull request.
.. figure:: /_images/examplePullReq.png
:scale: 35%
:align: center
Then finally click "Create pull request" to complete the pull request.
Your documents will be reviewed. To this same branch make the changes requested from the review and then push your new changes. There is no need to create another pull request.
.. code-block:: console
$ git commit -m 'A descriptive commit message for the new changes'
$ git push origin <branch name>
Additional Git commands
_______________________
You may find some of these Git commands useful:
Use **git diff** to quickly show the file changes and repo differences of your commits.
Use **git rm FILENAME** to stop tracking a file and to remove it from your remote branch and local directory. Use flag **-r** to remove folders/directories. E.g (**git rm -r oldfolder**)
.. _fdioDocs: https://github.com/fdioDocs/vpp-docs

130
docs/gettingstarted/writingdocs/readthedocs.rst
View File

@ -1,130 +0,0 @@
.. _readthedocs:
*******************
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

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.