-----------
To test how the documentation renders in HTML, follow these steps:
-Install virtual environment.
+Install `virtual environment <https://pypi.org/project/virtualenv>`_ & create one.
.. code-block:: bash
sudo pip install virtualenv
- cd /local/repo/path/to/project
+ virtualenv onap_docs
+
+Activate `onap_docs` virtual environment.
+
+.. code-block:: bash
+
+ source onap_docs/bin/activate
+
+.. note:: Virtual environment activation has to be performed before attempting to build documentation.
+ Otherwise, tools necessary for the process might not be available.
+
+Download a project repository.
+
+.. code-block:: bash
+
+ git clone http://gerrit.onap.org/r/<project>
Download the doc repository.
.. code-block:: bash
cd doc
- sudo pip install -r etc/requirements.txt
+ pip install -r etc/requirements.txt
-Move the conf.py file to your project folder where RST files have been kept:
+Copy the conf.py file to your project folder where RST files have been kept:
.. code-block:: bash
- mv doc/docs/conf.py <path-to-your-folder>/
+ cp docs/conf.py <path-to-project-folder>/<folder where are rst files>
-Move the static files to your project folder:
+Copy the static files to the project folder where RST files have been kept:
.. code-block:: bash
- mv docs/_static/ <path-to-your-folder>/
+ cp -r docs/_static/ <path-to-project-folder>/<folder where are rst files>
Build the documentation from within your project folder:
.. code-block:: bash
- sphinx-build -b html <path-to-your-folder> <path-to-output-folder>
+ sphinx-build -b html <path-to-project-folder>/<folder where are rst files> <path-to-output-folder>
Your documentation shall be built as HTML inside the
specified output folder directory.
+You can use your Web Browser to open
+and check resulting html pages in the output folder.
+
.. note:: Be sure to remove the `conf.py`, the static/ files and the output folder from the `<project>/docs/`. This is for testing only. Only commit the rst files and related content.
.. _building-all-documentation:
-----------------
To build the all documentation under doc/, follow these steps:
-Install virtual environment.
+Install `tox <https://pypi.org/project/tox>`_.
.. code-block:: bash
- sudo pip install virtualenv
- cd /local/repo/path/to/project
+ sudo pip install tox
Download the DOC repository.
by the doc project.
There are additional tox environment options for checking External
-URLs and Spelling. Use the tox environment options below and then
+URLs and Spelling. Use the tox environment options below and then
look at the output with the Linux `more` or similar command
scan for output that applies to the files you are validating.