Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 1 | .. This work is licensed under a Creative Commons Attribution 4.0 International License. |
| 2 | |
| 3 | Addendum |
| 4 | ======== |
| 5 | |
| 6 | Index File |
Rich Bennett | 976bffd | 2017-08-15 07:56:32 -0400 | [diff] [blame] | 7 | ---------- |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 8 | |
| 9 | The index file must relatively reference your other rst files in that directory. |
| 10 | |
| 11 | Here is an example index.rst : |
| 12 | |
| 13 | .. code-block:: bash |
| 14 | |
| 15 | ******************* |
| 16 | Documentation Title |
| 17 | ******************* |
| 18 | |
| 19 | .. toctree:: |
| 20 | :numbered: |
| 21 | :maxdepth: 2 |
| 22 | |
| 23 | documentation-example |
| 24 | |
| 25 | Source Files |
Rich Bennett | 976bffd | 2017-08-15 07:56:32 -0400 | [diff] [blame] | 26 | ------------ |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 27 | |
| 28 | Document source files have to be written in reStructuredText format (rst). |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 29 | Each file would be built as an html page. |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 30 | |
| 31 | Here is an example source rst file : |
| 32 | |
| 33 | .. code-block:: bash |
| 34 | |
| 35 | ============= |
| 36 | Chapter Title |
| 37 | ============= |
| 38 | |
| 39 | Section Title |
| 40 | ============= |
| 41 | |
| 42 | Subsection Title |
| 43 | ---------------- |
| 44 | |
| 45 | Hello! |
| 46 | |
| 47 | Writing RST Markdown |
Rich Bennett | 976bffd | 2017-08-15 07:56:32 -0400 | [diff] [blame] | 48 | -------------------- |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 49 | |
| 50 | See http://sphinx-doc.org/rest.html . |
| 51 | |
| 52 | **Hint:** |
| 53 | You can add html content that only appears in html output by using the |
| 54 | 'only' directive with build type |
| 55 | ('html' and 'singlehtml') for an ONAP document. But, this is not encouraged. |
| 56 | |
| 57 | .. code-block:: bash |
| 58 | |
| 59 | .. only:: html |
| 60 | This line will be shown only in html version. |
| 61 | |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 62 | |
Spencer Seidel | a10d3f5 | 2017-09-07 13:58:17 -0400 | [diff] [blame] | 63 | .. index:: single: indices |
| 64 | |
| 65 | Creating Indices |
| 66 | ---------------- |
| 67 | |
| 68 | Building an index for your Sphinx project is relatively simple. First, tell Sphinx that |
| 69 | you want it to build an index by adding something like this after your TOC tree: |
| 70 | |
| 71 | .. code-block:: rst |
| 72 | |
| 73 | Indices and Search |
| 74 | ================== |
| 75 | |
| 76 | * :ref:`genindex` |
| 77 | * :ref:`search` |
| 78 | |
| 79 | **Hint:** |
| 80 | Note that search was included here. It works out of the box with any Sphinx project, so you |
| 81 | don't need to do anything except include a reference to it in your :code:`index.rst` file. |
| 82 | |
| 83 | Now, to generate a index entry in your RST, do one of the following: |
| 84 | |
| 85 | .. code-block:: rst |
| 86 | |
| 87 | Some content that requires an :index:`index`. |
| 88 | |
| 89 | or |
| 90 | |
| 91 | .. code-block:: rst |
| 92 | |
| 93 | .. index:: |
| 94 | single: myterm |
| 95 | |
| 96 | Some header containing myterm |
| 97 | ============================= |
| 98 | |
| 99 | In the second case, Sphinx will create a link in the index to the paragraph that follows |
| 100 | the index entry declaration. |
| 101 | |
| 102 | When your project is built, Sphinx will generate an index page populated with the entries |
| 103 | you created in the source RST. |
| 104 | |
| 105 | These are simple cases with simple options. For more information about indexing with Sphinx, |
| 106 | please see the `official Sphinx documentation <http://www.sphinx-doc.org/en/stable/markup/misc.html#directive-index>`_. |
| 107 | |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 108 | |
Rich Bennett | 976bffd | 2017-08-15 07:56:32 -0400 | [diff] [blame] | 109 | Jenkins Jobs |
| 110 | ------------ |
| 111 | |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 112 | Verify Job |
Rich Bennett | 976bffd | 2017-08-15 07:56:32 -0400 | [diff] [blame] | 113 | ++++++++++ |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 114 | |
Rich Bennett | 976bffd | 2017-08-15 07:56:32 -0400 | [diff] [blame] | 115 | The verify job name is **doc-{stream}-verify-rtd** |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 116 | |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 117 | Proposed changes in files in any repository with the path |
| 118 | .. bash |
| 119 | docs/**/*.rst |
| 120 | |
| 121 | will be verified by this job prior to a gerrit code review. |
Rich Bennett | 976bffd | 2017-08-15 07:56:32 -0400 | [diff] [blame] | 122 | Please check the Jenkins log carefully for warnings. |
| 123 | You can improve your document even if the verify job succeeded. |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 124 | |
| 125 | Merge Job |
Rich Bennett | 976bffd | 2017-08-15 07:56:32 -0400 | [diff] [blame] | 126 | +++++++++ |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 127 | |
Rich Bennett | 976bffd | 2017-08-15 07:56:32 -0400 | [diff] [blame] | 128 | The merge job name is **doc-{stream}-merge-rtd**. |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 129 | |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 130 | When a committer merges a patch that includes files matching the path described above, |
| 131 | the doc project merge job will trigger an update at readthedocs. |
| 132 | This might take about 15 minutes while readthedocs |
| 133 | builds the documentation. |