Update git submodules

[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:
 .. _include-documentation:

-=============================================
+============================

 Including your Documentation
 Including your Documentation

-=============================================
+============================

 
 .. contents::
    :depth: 3
    :local:
 
 In your project repository
 
 .. 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
 
 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
    git review
 
 In OPNFVDocs Composite Documentation

---------------------------------------
+------------------------------------

 
 In toctree
 +++++++++++
 
 In toctree
 +++++++++++


@@ -70,7 +70,7 @@ it, example:
     <submodules/path-to-your-file>
 
 As Hyperlink
     <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
 
 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.
 
 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
 Testing: Build Documentation Locally

----------------------------------------
+------------------------------------

 
 Composite OPNFVDOCS documentation
 
 Composite OPNFVDOCS documentation

-+++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++

 To build whole documentation under opnfvdocs/, follow these steps:
 
 Install virtual environment.
 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
 .. 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.
 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.
 
 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
+