Merge "updated the license header to use the SPDX shorthand"

[opnfvdocs.git] / docs / how-to-use-docs / include-documentation.rst

diff --git a/docs/how-to-use-docs/include-documentation.rst b/docs/how-to-use-docs/include-documentation.rst
index f1f299e..1430b94 100644 (file)
--- a/docs/how-to-use-docs/include-documentation.rst
+++ b/docs/how-to-use-docs/include-documentation.rst
@@ -1,14 +1,14 @@
-
-=============================================
+.. _include-documentation:
+============================
 Including your Documentation
-=============================================
+============================
 
 .. contents::
    :depth: 3
    :local:
 
 In your project repository
-----------------------------
+--------------------------
 
 Add your documentation to your repository in the folder structure and
 according to the templates listed above. The documentation templates you
@@ -34,7 +34,7 @@ the documentation to the project repository.
    git review
 
 In OPNFVDocs Composite Documentation
---------------------------------------
+------------------------------------
 
 In toctree
 +++++++++++
@@ -70,7 +70,7 @@ it, example:
     <submodules/path-to-your-file>
 
 As Hyperlink
-+++++++++++++
+++++++++++++
 
 It's pretty common to want to reference another location in the
 OPNFV documentation and it's pretty easy to do with
@@ -125,3 +125,104 @@ the opnfvdocs team for review and integration.
 
 Be sure to add the project leader of the opnfvdocs project
 as a reviewer of the change you just pushed in gerrit.
+
+'doc8' Validation
+-----------------
+It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards.
+To validate your rst files using doc8, install doc8.
+
+.. code-block:: bash
+
+   sudo pip install doc8
+
+doc8 can now be used to check the rst files. Execute as,
+
+.. code-block:: bash
+
+   doc8 --ignore D000,D001 <file>
+
+
+Testing: Build Documentation Locally
+------------------------------------
+
+Composite OPNFVDOCS documentation
++++++++++++++++++++++++++++++++++
+To build whole documentation under opnfvdocs/, follow these steps:
+
+Install virtual environment.
+
+.. code-block:: bash
+
+   sudo pip install virtualenv
+   cd /local/repo/path/to/project
+
+Download the OPNFVDOCS repository.
+
+.. code-block:: bash
+
+   git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
+
+Change directory to opnfvdocs & install requirements.
+
+.. code-block:: bash
+
+   cd opnfvdocs
+   sudo pip install -r etc/requirements.txt
+
+Update submodules, build documentation using tox & then open using any browser.
+
+.. code-block:: bash
+
+   cd opnfvdocs
+   git submodule update --init
+   tox -edocs
+   firefox docs/_build/html/index.html
+
+.. note:: Make sure to run `tox -edocs` and not just `tox`.
+
+Individual project documentation
+++++++++++++++++++++++++++++++++
+To test how the documentation renders in HTML, follow these steps:
+
+Install virtual environment.
+
+.. code-block:: bash
+
+   sudo pip install virtualenv
+   cd /local/repo/path/to/project
+
+Download the opnfvdocs repository.
+
+.. code-block:: bash
+
+   git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
+
+Change directory to opnfvdocs & install requirements.
+
+.. code-block:: bash
+
+   cd opnfvdocs
+   sudo pip install -r etc/requirements.txt
+
+Move the conf.py file to your project folder where RST files have been kept:
+
+.. code-block:: bash
+
+   mv opnfvdocs/docs/conf.py <path-to-your-folder>/
+
+Move the static files to your project folder:
+
+.. code-block:: bash
+
+   mv opnfvdocs/_static/ <path-to-your-folder>/
+
+Build the documentation from within your project folder:
+
+.. code-block:: bash
+
+   sphinx-build -b html <path-to-your-folder> <path-to-output-folder>
+
+Your documentation shall be built as HTML inside the
+specified output folder directory.
+
+.. 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.