diff options
author | Rich Bennett <rb2745@att.com> | 2017-09-13 03:19:19 -0400 |
---|---|---|
committer | Rich Bennett <rb2745@att.com> | 2017-09-13 07:39:09 +0000 |
commit | 5baea4608e685f67e9dec77cfee57cacb73662dd (patch) | |
tree | 3f6349e6ef9a6c0eb487a721087d0644dafd73d8 /docs/guides/onap-developer/how-to-use-docs/addendum.rst | |
parent | a7f9e351a97b5b5b89e4e1eccd201a3e15e8f385 (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.rst | 133 |
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. |