diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/gettingstarted/developers/gitreview.rst (renamed from docs/gettingstarted/writingdocs/gitreview.rst) | 27 | ||||
| -rw-r--r-- | docs/gettingstarted/developers/index.rst | 1 | ||||
| -rw-r--r-- | docs/gettingstarted/developers/running_vpp.rst | 7 | ||||
| -rw-r--r-- | docs/gettingstarted/writingdocs/buildingrst.rst | 199 | ||||
| -rw-r--r-- | docs/gettingstarted/writingdocs/index.rst | 9 | ||||
| -rw-r--r-- | docs/gettingstarted/writingdocs/todo.rst | 55 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/links/index.rst | 33 | ||||
| -rw-r--r-- | docs/reference/github/index.rst (renamed from docs/gettingstarted/writingdocs/pushingapatch.rst) | 6 | ||||
| -rw-r--r-- | docs/reference/index.rst | 7 | ||||
| -rw-r--r-- | docs/reference/readthedocs/index.rst (renamed from docs/gettingstarted/writingdocs/readthedocs.rst) | 5 |
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. |