.. _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
========
$ 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:
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:
$ 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
+
+
+
.. _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
$ 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
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:
$ 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.
$ 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.
Code Review / vpp.git / commitdiff