diff options
Diffstat (limited to 'docs/guides/onap-developer/how-to-use-docs')
4 files changed, 153 insertions, 159 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 deleted file mode 100644 index e3b209cbe..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/addendum.rst +++ /dev/null @@ -1,158 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. http://creativecommons.org/licenses/by/4.0 - -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. - - -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>`_. - - -Jenkins Jobs ------------- - -Verify Job -++++++++++ - -The verify job name is **doc-{stream}-verify-rtd** - -Proposed changes in files in any repository with top level docs folder -in the repository and RST files in below this folder -will be verified by this job as part of a gerrit code review. - -.. Important:: - The contributing author and every reviewer on a gerrit code review - should always review the Jenkins log before approving and merging a - change. The log review should include: - - * Using a browser or other editor to search for a pattern in the - *console log* that matches files in the patch set. This will quickly - identify errors and warnings that are related to the patch set and - repository being changed. - - * Using a browser to click on the *html* folder included in the log - and preview how the proposed changes will look when published at - Read The Docs. Small changes can be easily made in the patch set. - -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. There may be some delay after the merge job -completes until new version appears at Read The Docs. - -Read The Docs URLs ------------------- - -When referencing versions of documentation a Read The Docs the following -URL conventions should be used - - +----------------------------------+----------------------------------------+ - | URL | To Refer to | - +==================================+========================================+ - | docs.onap.org | Most recent approved named release | - +----------------------------------+----------------------------------------+ - | docs.onap.org/en/latest | Latest master branch all projects | - +----------------------------------+----------------------------------------+ - | docs.onap.org/en/*named release* | An approved name release eg. amsterdam | - +----------------------------------+----------------------------------------+ diff --git a/docs/guides/onap-developer/how-to-use-docs/index.rst b/docs/guides/onap-developer/how-to-use-docs/index.rst index 2e7e47acf..3c65f331a 100644 --- a/docs/guides/onap-developer/how-to-use-docs/index.rst +++ b/docs/guides/onap-developer/how-to-use-docs/index.rst @@ -14,7 +14,6 @@ Creating Documentation api-swagger-guide templates converting-to-rst - addendum .. toctree:: :hidden: diff --git a/docs/guides/onap-developer/how-to-use-docs/introduction.rst b/docs/guides/onap-developer/how-to-use-docs/introduction.rst index 250313fc4..242a2d239 100644 --- a/docs/guides/onap-developer/how-to-use-docs/introduction.rst +++ b/docs/guides/onap-developer/how-to-use-docs/introduction.rst @@ -208,3 +208,19 @@ files: When there are subsequent, significant contributions to a source file from a different contributor, a new copyright line may be appended after the last existing copyright line. + +Read The Docs URLs +------------------ + +When referencing versions of documentation a Read The Docs the following +URL conventions should be used + + +----------------------------------+----------------------------------------+ + | URL | To Refer to | + +==================================+========================================+ + | docs.onap.org | Most recent approved named release | + +----------------------------------+----------------------------------------+ + | docs.onap.org/en/latest | Latest master branch all projects | + +----------------------------------+----------------------------------------+ + | docs.onap.org/en/*named release* | An approved name release eg. amsterdam | + +----------------------------------+----------------------------------------+ diff --git a/docs/guides/onap-developer/how-to-use-docs/setting-up.rst b/docs/guides/onap-developer/how-to-use-docs/setting-up.rst index 509e7aff1..789cf0b9d 100644 --- a/docs/guides/onap-developer/how-to-use-docs/setting-up.rst +++ b/docs/guides/onap-developer/how-to-use-docs/setting-up.rst @@ -409,6 +409,143 @@ Because the labels have to be unique, it usually makes sense to prefix the labels with the project name to help share the label space, e.g., ``sfc-user-guide`` instead of just ``user-guide``. +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. + + +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>`_. + + +Jenkins Jobs +------------ + +Verify Job +++++++++++ + +The verify job name is **doc-{stream}-verify-rtd** + +Proposed changes in files in any repository with top level docs folder +in the repository and RST files in below this folder +will be verified by this job as part of a gerrit code review. + +.. Important:: + The contributing author and every reviewer on a gerrit code review + should always review the Jenkins log before approving and merging a + change. The log review should include: + + * Using a browser or other editor to search for a pattern in the + *console log* that matches files in the patch set. This will quickly + identify errors and warnings that are related to the patch set and + repository being changed. + + * Using a browser to click on the *html* folder included in the log + and preview how the proposed changes will look when published at + Read The Docs. Small changes can be easily made in the patch set. + +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. There may be some delay after the merge job +completes until new version appears at Read The Docs. + Testing ======= |