Merge "Documenting OPNFV GCE machins"

[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 010ed4f..d1a5a62 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
@@ -126,11 +126,27 @@ 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.
@@ -165,7 +181,7 @@ Update submodules, build documentation using tox & then open using any browser.
 .. 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.
@@ -208,3 +224,31 @@ Build the documentation from within your project 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.
+
+
+Adding your project repository as a submodule
+--------------------------
+
+Clone the opnfvdocs repository and your submodule to .gitmodules following the convention of the file
+
+.. code-block:: bash
+
+  cd docs/submodules/
+  git submodule add https://gerrit.opnfv.org/gerrit/$reponame
+  git submodule init $reponame/
+  git submodule update $reponame/
+  git add .
+  git commit -sv
+  git review
+
+Removing a project repository as a submodule
+--------------------------
+  git rm docs/submodules/$reponame
+  rm -rf .git/modules/$reponame
+  git config -f .git/config --remove-section submodule.$reponame 2> /dev/null
+  git add .
+  git commit -sv
+  git review
+