aboutsummaryrefslogtreecommitdiffstats
path: root/docs/gettingstarted/writingdocs/buildingrst.rst
diff options
context:
space:
mode:
authorJohn DeNisco <jdenisco@cisco.com>2018-07-26 12:45:10 -0400
committerDave Barach <openvpp@barachs.net>2018-07-26 18:34:47 +0000
commit06dcd45ff81e06bc8cf40ed487c0b2652d346a5a (patch)
tree71403f9d422c4e532b2871a66ab909bd6066b10b /docs/gettingstarted/writingdocs/buildingrst.rst
parent1d65279ffecd0f540288187b94cb1a6b84a7a0c6 (diff)
Initial commit of Sphinx docs
Change-Id: I9fca8fb98502dffc2555f9de7f507b6f006e0e77 Signed-off-by: John DeNisco <jdenisco@cisco.com>
Diffstat (limited to 'docs/gettingstarted/writingdocs/buildingrst.rst')
-rw-r--r--docs/gettingstarted/writingdocs/buildingrst.rst236
1 files changed, 236 insertions, 0 deletions
diff --git a/docs/gettingstarted/writingdocs/buildingrst.rst b/docs/gettingstarted/writingdocs/buildingrst.rst
new file mode 100644
index 00000000000..00f051c30b7
--- /dev/null
+++ b/docs/gettingstarted/writingdocs/buildingrst.rst
@@ -0,0 +1,236 @@
+.. _buildingrst:
+
+**********************
+Building VPP Documents
+**********************
+
+Overview
+========
+
+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`_.
+
+
+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.
+
+.. code-block:: console
+
+ $ git clone https://gerrit.fd.io/r/vpp
+ $ cd vpp
+
+
+Install the virtual environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In your vpp-docs directory, run:
+
+.. code-block:: console
+
+ $ python -m pip install --user virtualenv
+ $ python -m virtualenv env
+ $ source env/bin/activate
+ $ pip install -r docs/etc/requirements.txt
+ $ cd docs
+
+Which installs all the required applications into it's own, isolated, virtual environment, so as to not
+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:
+
+.. code-block:: console
+
+ $ 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.
+
+.. figure:: /_images/htmlBuild.png
+ :alt: Figure: My directory containing the index.html file
+ :scale: 35%
+ :align: center
+
+Whenever you make changes to your **.rst** files that you want to see, repeat this build process.
+
+.. note::
+
+ To exit from the virtual environment execute:
+
+.. code-block:: console
+
+ $ deactivate
+
+
+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