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>
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.
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.
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.
.. _include-documentation:
.. _include-documentation:
-=============================================
+=============================
Including your Documentation
Including your Documentation
-=============================================
+=============================
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
---------------------------------------
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.
-..
- This is new template created on Nov 27, 2015.
-*********************
-Example Documentation
-*********************
+================================
+How to work with Documentation
+================================
- documentation-example.rst
+ documentation-guide
+ include-documentation