10 These instructions show how the VPP documentation sources are built.
12 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/>`_.
13 We will also cover how to view your build on Read the Docs in `Using Read the Docs`_.
16 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`_.
18 Create a Virtual Environment using virtualenv
19 _____________________________________________
21 For more information on how to use the Python virtual environment check out
22 `Installing packages using pip and virtualenv`_.
24 .. _`Installing packages using pip and virtualenv`: https://packaging.python.org/guides/installing-using-pip-and-virtualenv/
29 For example start with a clone of the vpp-docs.
31 .. code-block:: console
33 $ git clone https://gerrit.fd.io/r/vpp
37 Install the virtual environment
38 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
40 In your vpp-docs directory, run:
42 .. code-block:: console
44 $ python -m pip install --user virtualenv
45 $ python -m virtualenv env
46 $ source env/bin/activate
47 $ pip install -r docs/etc/requirements.txt
50 Which installs all the required applications into it's own, isolated, virtual environment, so as to not
51 interfere with other builds that may use different versions of software.
56 Be sure you are in your vpp-docs/docs directory, since that is where Sphinx will look for your **conf.py**
57 file, and build the **.rst** files into an **index.html** file:
59 .. code-block:: console
66 | If there are no errors during the build process, you should now have an **index.html** file in your
67 | **vpp/docs/_build/html** directory, which you can then view in your browser.
69 .. figure:: /_images/htmlBuild.png
70 :alt: Figure: My directory containing the index.html file
74 Whenever you make changes to your **.rst** files that you want to see, repeat this build process.
78 To exit from the virtual environment execute:
80 .. code-block:: console
85 Install Sphinx manually
86 _______________________
88 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>`_.
90 Building these files will generate an **index.html** file, which you can then view in your browser to verify and see your file changes.
93 To *build* your files, make sure you're in your **vpp-docs/docs** directory, where your **conf.py** file is located, and run:
95 .. code-block:: console
100 | If there are no errors during the build process, you should now have an **index.html** file in your
101 | **vpp-docs/docs/_build/html** directory, which you can then view in your browser.
103 .. figure:: /_images/htmlBuild.png
107 Whenever you make changes to your **.rst** files that you want to see, repeat this build process.
113 `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.
115 Create an account on *Read the Docs* if you haven't already.
117 Go to your `dashboard <https://readthedocs.org/dashboard/>`_ , and click on "Import a Project".
119 .. figure:: /_images/importReadDocs.png
123 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".
135 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".
138 .. figure:: /_images/importRTDManually.png
167 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.
169 Then click on "Build Version".
171 .. figure:: /_images/buildVerRTD.png
199 Which takes you to another page showing your recent builds.
201 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".
204 .. figure:: /_images/passedBuild.png
232 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!
234 .. figure:: /_images/rtdWebpage.png