Update OPNFVDocs documentation

1. Added note about eliminating conf.py etc
from include-documentation.
2. Eliminated content about enabling toolchain
since its irrelevant after migration to RTD
3. Added steps to validate using doc8
4. Populated index page.

Change-Id: I80c8354fd4da4bca0b8f338c178f0773d834b6ee
Signed-off-by: ShubhamRathi <shubhamiiitbackup@gmail.com>

diff --git a/docs/how-to-use-docs/documentation-guide.rst b/docs/how-to-use-docs/documentation-guide.rst
index aeabdcc..3c84468 100644 (file)
--- a/docs/how-to-use-docs/documentation-guide.rst
+++ b/docs/how-to-use-docs/documentation-guide.rst
@@ -15,11 +15,6 @@ OPNFV documentation is automated and integrated into our git & gerrit toolchains
 We use RST document templates in our repositories and automatically render to HTML and PDF versions of the documents in our artifact store, our WiKi is also able to integrate these rendered documents directly allowing projects to use the revision controlled documentation process for project information, content and deliverables.
 Read :ref:`this page <include-documentation>` which elaborates on how documentation is to be included within opnfvdocs.
 
-Enabling the documentation toolchain in your project
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-There are some basic steps you will need to perform in order to get the toolchain working in your repository, this include setting up Jenkins jobs and establishing your project documentation structure. See the document toolchain instructions for more details on getting started in your project.
-The linked page above is written completely in generated artifacts, check the source to see how to do it yourself!
-
 Licencing your documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 All contributions to the OPNFV project are done in accordance with the OPNFV licensing requirements. Documentation in OPNFV is contributed in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ licence.

diff --git a/docs/how-to-use-docs/include-documentation.rst b/docs/how-to-use-docs/include-documentation.rst
index 010ed4f..4cf9f27 100644 (file)
--- a/docs/how-to-use-docs/include-documentation.rst
+++ b/docs/how-to-use-docs/include-documentation.rst
@@ -1,7 +1,7 @@
 .. _include-documentation:
-=============================================
+=============================
 Including your Documentation
-=============================================
+=============================
 
 .. contents::
    :depth: 3
@@ -126,6 +126,22 @@ 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
 ---------------------------------------
 
@@ -208,3 +224,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.

diff --git a/docs/how-to-use-docs/index.rst b/docs/how-to-use-docs/index.rst
index 8e4dbd2..5839a8b 100644 (file)
--- a/docs/how-to-use-docs/index.rst
+++ b/docs/how-to-use-docs/index.rst
@@ -1,12 +1,10 @@
-..
-    This is new template created on Nov 27, 2015.
 
-*********************
-Example Documentation
-*********************
+================================
+How to work with Documentation
+================================
 
 .. toctree::
-   :numbered:
    :maxdepth: 2
 
-   documentation-example.rst
+   documentation-guide
+   include-documentation