X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fhow-to-use-docs%2Finclude-documentation.rst;h=d1a5a6227f4535fb81473b09b9203e34602658da;hb=95e116314a3e65bc0a0a4edf91dedc33156038c8;hp=da134d1c055a2371fa6a1dee09a8e6b587dc9b2b;hpb=5b3ebcd9d88af2288597576783ee2d027a17652a;p=opnfvdocs.git

diff --git a/docs/how-to-use-docs/include-documentation.rst b/docs/how-to-use-docs/include-documentation.rst
index da134d1c0..d1a5a6227 100644
--- 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
+