[pcac] clean-up of broken links and outdated text

[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..78abfc6 100644 (file)
--- a/docs/how-to-use-docs/include-documentation.rst
+++ b/docs/how-to-use-docs/include-documentation.rst
@@ -1,14 +1,15 @@
 .. _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,16 +35,7 @@ the documentation to the project repository.
    git review
 
 In OPNFVDocs Composite Documentation
---------------------------------------
-
-In toctree
-+++++++++++
-
-To import project documents from project repositories, we use submodules.
- Each project is stored in :code:`opnfvdocs/docs/submodule/` as follows:
-
-.. image:: Submodules.jpg
-   :scale: 50 %
+------------------------------------
 
 To include your project specific documentation in the composite documentation,
 first identify where your project documentation should be included.
@@ -70,13 +62,13 @@ 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
 reStructuredText. This is a quick primer, more information is in the
 `Sphinx section on Cross-referencing arbitrary locations
-<http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.
+<http://www.sphinx-doc.org/en/stable/markup/inline.html#roles>`_.
 
 Within a single document, you can reference another section simply by::
 
@@ -126,11 +118,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 +173,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 +216,5 @@ 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.