aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAric Gardner <agardner@linuxfoundation.org>2015-09-10 15:41:09 -0400
committerAric Gardner <agardner@linuxfoundation.org>2015-09-10 15:41:17 -0400
commited6de63572d92bb5af8be22ced0a749400f4d3d4 (patch)
tree07a4b43862d987ac0763fce9da7db4eb1f2aee6b
parent123ab6c7e1d0fd6e0a6880814ab731b140539e91 (diff)
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: I53a904d9340a8dda554cf219362123df765275b6 JIRA:RELENG-15 Signed-off-by: Aric Gardner <agardner@linuxfoundation.org>
-rw-r--r--docs/etc/conf.py34
-rw-r--r--docs/etc/opnfv-logo.pngbin0 -> 2829 bytes
-rw-r--r--docs/how-to-use-docs/documentation-example.rst86
-rw-r--r--docs/how-to-use-docs/index.rst30
4 files changed, 150 insertions, 0 deletions
diff --git a/docs/etc/conf.py b/docs/etc/conf.py
new file mode 100644
index 00000000..00660351
--- /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 00000000..1519503e
--- /dev/null
+++ b/docs/etc/opnfv-logo.png
Binary files differ
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 00000000..afcf7581
--- /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 00000000..36710b32
--- /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|