From b177ac85ca0d0bdeac4b6e37847b341b0b568f47 Mon Sep 17 00:00:00 2001
From: Aric Gardner <agardner@linuxfoundation.org>
Date: Thu, 31 Mar 2016 15:41:11 -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, these files are only meant as place holders
and should be replaced by your own project documentation

Change-Id: I3c61ef2dac43d55f4cf6c6677099fef8b101a182
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 0000000..0066035
--- /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 0000000..afcf758
--- /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 0000000..36710b3
--- /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