Add Documentation Guide

This is based on the spectrometer documentation guide and was ported
over and modified.

Also:

- Adds the .tox/ directory to .gitignore.
- Change toctree depth to 1 since we have more guides listed now

Change-Id: Ic129c6cfd01794245f6ea25f69f18b0849410a7f
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

diff --git a/.gitignore b/.gitignore
index 711a8e75a26f19dbb89d276a207b047e00ae07e3..8e8d55bc0746675d2811de2fe12ee85b7e3d418f 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,6 @@ target
 *.iws
 *~
 .DS_Store
+
+# Python
+.tox/

diff --git a/docs/documentation.rst b/docs/documentation.rst
new file mode 100644 (file)
index 0000000..45a899f
--- /dev/null
+++ b/docs/documentation.rst
@@ -0,0 +1,25 @@
+.. _documentation-guide:
+
+Documentation Guide
+===================
+
+This guide provides details on how to contribute to the documetantion of
+Spectrometer. The style guide we follow for documentation is the python
+documentation style guide. See:
+
+    https://docs.python.org/devguide/documenting.html
+
+To build and review the documentation locally you first require to have
+installed locally:
+
+* python
+* python-tox
+
+Which both should be available in most distribution's package managers.
+
+Then simply run tox and open the html produced via your favourite web browser.
+
+.. code-block:: bash
+
+    tox -edocs
+    firefox .tox/docs/tmp/html/index.html

diff --git a/docs/index.rst b/docs/index.rst
index 1ecabbe62ebf325e286cde7981a7f015870e24e4..ea58d6c59684b0f559a8378f5b5b8746572b064d 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,14 +6,21 @@
 Welcome to the OpenDaylight Handbook!
 =====================================
 
+This handbook provides details on various aspects of OpenDaylight from the user
+guides to the developer guides and tries to act as a single point of contact
+for all documentation related articles in OpenDaylight. If you would like to
+contribute to the Handbook please refer to the :ref:`documentation-guide`.
+
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+
 
    getting-started-guide/index
    opendaylight-with-openstack/index
    submodules/releng/builder/docs/index
+   documentation
 
 Indices and tables
 ==================