summaryrefslogtreecommitdiffstats
path: root/docs/guides/onap-developer/how-to-use-docs/addendum.rst
diff options
context:
space:
mode:
authorRich Bennett <rb2745@att.com>2017-09-13 03:19:19 -0400
committerRich Bennett <rb2745@att.com>2017-09-13 07:39:09 +0000
commit5baea4608e685f67e9dec77cfee57cacb73662dd (patch)
tree3f6349e6ef9a6c0eb487a721087d0644dafd73d8 /docs/guides/onap-developer/how-to-use-docs/addendum.rst
parenta7f9e351a97b5b5b89e4e1eccd201a3e15e8f385 (diff)
Enhancement and additions for webinar
Add templates, revise master index, guides, and release document Improve project integration instructions based on 5 project integrations. Change-Id: I2a3e62737f3c126b7f5fb7cc4f53b35dba4f1d8f Issue-ID: DOC-26 Signed-off-by: Rich Bennett <rb2745@att.com>
Diffstat (limited to 'docs/guides/onap-developer/how-to-use-docs/addendum.rst')
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/addendum.rst133
1 files changed, 133 insertions, 0 deletions
diff --git a/docs/guides/onap-developer/how-to-use-docs/addendum.rst b/docs/guides/onap-developer/how-to-use-docs/addendum.rst
new file mode 100644
index 000000000..160b18fde
--- /dev/null
+++ b/docs/guides/onap-developer/how-to-use-docs/addendum.rst
@@ -0,0 +1,133 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Addendum
+========
+
+Index File
+----------
+
+The index file must relatively reference your other rst files in that directory.
+
+Here is an example index.rst :
+
+.. code-block:: bash
+
+ *******************
+ Documentation Title
+ *******************
+
+ .. toctree::
+ :numbered:
+ :maxdepth: 2
+
+ documentation-example
+
+Source Files
+------------
+
+Document source files have to be written in reStructuredText format (rst).
+Each file would be built as an html page.
+
+Here is an example source rst file :
+
+.. code-block:: bash
+
+ =============
+ Chapter Title
+ =============
+
+ Section Title
+ =============
+
+ Subsection Title
+ ----------------
+
+ Hello!
+
+Writing RST Markdown
+--------------------
+
+See http://sphinx-doc.org/rest.html .
+
+**Hint:**
+You can add html content that only appears in html output by using the
+'only' directive with build type
+('html' and 'singlehtml') for an ONAP document. But, this is not encouraged.
+
+.. code-block:: bash
+
+ .. only:: html
+ This line will be shown only in html version.
+
+
+.. index:: single: indices
+
+Creating Indices
+----------------
+
+Building an index for your Sphinx project is relatively simple. First, tell Sphinx that
+you want it to build an index by adding something like this after your TOC tree:
+
+.. code-block:: rst
+
+ Indices and Search
+ ==================
+
+ * :ref:`genindex`
+ * :ref:`search`
+
+**Hint:**
+Note that search was included here. It works out of the box with any Sphinx project, so you
+don't need to do anything except include a reference to it in your :code:`index.rst` file.
+
+Now, to generate a index entry in your RST, do one of the following:
+
+.. code-block:: rst
+
+ Some content that requires an :index:`index`.
+
+or
+
+.. code-block:: rst
+
+ .. index::
+ single: myterm
+
+ Some header containing myterm
+ =============================
+
+In the second case, Sphinx will create a link in the index to the paragraph that follows
+the index entry declaration.
+
+When your project is built, Sphinx will generate an index page populated with the entries
+you created in the source RST.
+
+These are simple cases with simple options. For more information about indexing with Sphinx,
+please see the `official Sphinx documentation <http://www.sphinx-doc.org/en/stable/markup/misc.html#directive-index>`_.
+
+
+Jenkins Jobs
+------------
+
+Verify Job
+++++++++++
+
+The verify job name is **doc-{stream}-verify-rtd**
+
+Proposed changes in files in any repository with the path
+.. bash
+ docs/**/*.rst
+
+will be verified by this job prior to a gerrit code review.
+Please check the Jenkins log carefully for warnings.
+You can improve your document even if the verify job succeeded.
+
+Merge Job
++++++++++
+
+The merge job name is **doc-{stream}-merge-rtd**.
+
+When a committer merges a patch that includes files matching the path described above,
+the doc project merge job will trigger an update at readthedocs.
+This might take about 15 minutes while readthedocs
+builds the documentation.