diff options
| -rw-r--r-- | docs/how-to-use-docs/documentation-guide.rst | 5 | ||||
| -rw-r--r-- | docs/how-to-use-docs/include-documentation.rst | 22 | ||||
| -rw-r--r-- | docs/how-to-use-docs/index.rst | 12 |
3 files changed, 25 insertions, 14 deletions
diff --git a/docs/how-to-use-docs/documentation-guide.rst b/docs/how-to-use-docs/documentation-guide.rst index aeabdcc0d..3c8446893 100644 --- 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 010ed4f7b..4cf9f2757 100644 --- 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 8e4dbd266..5839a8b7b 100644 --- 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 |