From cc84a1f21026270463b580f2564f9d71912b20db Mon Sep 17 00:00:00 2001
From: Aric Gardner <agardner@linuxfoundation.org>
Date: Thu, 10 Sep 2015 15:37:26 -0400
Subject: [PATCH] Example as code, documentation template for sphinx build

This code will be pushed to each project creating a docs/ directory
This servers as an example and template for you (the developers) to create
your own project documentation

Change-Id: I8aa7b356e320ab83c902604c9bf66f56c16ae643
JIRA:RELENG-15
Signed-off-by: Aric Gardner <agardner@linuxfoundation.org>
---
 docs/etc/conf.py                               |  34 ++++++++++
 docs/etc/opnfv-logo.png                        | Bin 0 -> 2829 bytes
 docs/how-to-use-docs/documentation-example.rst |  86 +++++++++++++++++++++++++
 docs/how-to-use-docs/index.rst                 |  30 +++++++++
 4 files changed, 150 insertions(+)
 create mode 100644 docs/etc/conf.py
 create mode 100644 docs/etc/opnfv-logo.png
 create mode 100644 docs/how-to-use-docs/documentation-example.rst
 create mode 100644 docs/how-to-use-docs/index.rst

diff --git a/docs/etc/conf.py b/docs/etc/conf.py
new file mode 100644
index 000000000..006603516
--- /dev/null
+++ b/docs/etc/conf.py
@@ -0,0 +1,34 @@
+import datetime
+import sys
+import os
+
+try:
+    __import__('imp').find_module('sphinx.ext.numfig')
+    extensions = ['sphinx.ext.numfig']
+except ImportError:
+    # 'pip install sphinx_numfig'
+    extensions = ['sphinx_numfig']
+
+# numfig:
+number_figures = True
+figure_caption_prefix = "Fig."
+
+source_suffix = '.rst'
+master_doc = 'index'
+pygments_style = 'sphinx'
+html_use_index = False
+
+pdf_documents = [('index', u'OPNFV', u'OPNFV Project', u'OPNFV')]
+pdf_fit_mode = "shrink"
+pdf_stylesheets = ['sphinx','kerning','a4']
+#latex_domain_indices = False
+#latex_use_modindex = False
+
+latex_elements = {
+    'printindex': '',
+}
+
+project = u'OPNFV: Template documentation config'
+copyright = u'%s, OPNFV' % datetime.date.today().year
+version = u'1.0.0'
+release = u'1.0.0'
diff --git a/docs/etc/opnfv-logo.png b/docs/etc/opnfv-logo.png
new file mode 100644
index 0000000000000000000000000000000000000000..1519503eba764f7a00877b9b8bdbbd37fd3707c6
GIT binary patch
literal 2829
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

literal 0
HcmV?d00001

diff --git a/docs/how-to-use-docs/documentation-example.rst b/docs/how-to-use-docs/documentation-example.rst
new file mode 100644
index 000000000..afcf75814
--- /dev/null
+++ b/docs/how-to-use-docs/documentation-example.rst
@@ -0,0 +1,86 @@
+.. two dots create a comment. please leave this logo at the top of each of your rst files.
+.. image:: ../etc/opnfv-logo.png 
+  :height: 40
+  :width: 200
+  :alt: OPNFV
+  :align: left
+.. these two pipes are to seperate the logo from the first title
+|
+|
+How to create documentation for your OPNFV project
+==================================================
+
+this is the directory structure of the docs/ directory that can be found in the root of your project directory
+
+.. code-block:: bash
+
+    ./etc
+    ./etc/opnfv-logo.png
+    ./etc/conf.py
+    ./how-to-use-docs
+    ./how-to-use-docs/documentation-example.rst
+    ./how-to-use-docs/index.rst
+
+To create your own documentation, Create any number of directories (depending on your need) and place in each of them an index.rst.
+This index file must refence your other rst files.
+
+* Here is an example index.rst
+
+.. code-block:: bash
+
+  Example Documentation table of contents
+  =======================================
+
+  Contents:
+
+  .. toctree::
+     :numbered:
+     :maxdepth: 4
+
+     documentation-example.rst
+
+  Indices and tables
+  ==================
+
+  * :ref:`search`
+
+  Revision: _sha1_
+
+  Build date: |today|
+
+
+The Sphinx Build
+================
+
+When you push documentation changes to gerrit a jenkins job will create html documentation.
+
+* Verify Jobs
+For verify jobs a link to the documentation will show up as a comment in gerrit for you to see the result.
+
+* Merge jobs
+
+Once you are happy with the look of your documentation you can submit the patchset the merge job will 
+copy the output of each documentation directory to http://artifacts.opnfv.org/$project/docs/$name_of_your_folder/index.html
+
+Here are some quick examples of how to use rst markup
+
+This is a headline::
+
+  here is some code, note that it is indented
+
+links are easy to add: Here is a link to sphinx, the tool that we are using to generate documetation http://sphinx-doc.org/
+
+* Bulleted Items
+
+  **this will be bold**
+
+.. code-block:: bash
+
+  echo "Heres is a code block with bash syntax highlighting"
+
+
+Leave these at the bottom of each of your documents they are used internally
+
+Revision: _sha1_
+
+Build date: |today|
diff --git a/docs/how-to-use-docs/index.rst b/docs/how-to-use-docs/index.rst
new file mode 100644
index 000000000..36710b32d
--- /dev/null
+++ b/docs/how-to-use-docs/index.rst
@@ -0,0 +1,30 @@
+.. OPNFV Release Engineering documentation, created by
+   sphinx-quickstart on Tue Jun  9 19:12:31 2015.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. image:: ../etc/opnfv-logo.png
+  :height: 40
+  :width: 200
+  :alt: OPNFV
+  :align: left
+
+Example Documentation table of contents
+=======================================
+
+Contents:
+
+.. toctree::
+   :numbered:
+   :maxdepth: 4
+
+   documentation-example.rst
+
+Indices and tables
+==================
+
+* :ref:`search`
+
+Revision: _sha1_
+
+Build date: |today|
-- 
2.16.6