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 | |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 3 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 4 | Setting Up |
| 5 | ========== |
jsseidel | da2324a | 2017-09-15 10:43:14 -0400 | [diff] [blame^] | 6 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 7 | Some initial set up is required to connect a project with |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 8 | the master document structure and enable automated publishing of |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 9 | changes as summarized in the following diagram and description below |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 10 | below. |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 11 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 12 | .. seqdiag:: |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 13 | :height: 700 |
| 14 | :width: 1000 |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 15 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 16 | seqdiag { |
| 17 | RD [label = "Read The Docs", color =lightgreen ]; |
| 18 | DA [label = "Doc Project\nAuthor/Committer", color=lightblue]; |
| 19 | DR [label = "Doc Gerrit Repo" , color=pink]; |
| 20 | PR [label = "Other Project\nGerrit Repo", color=pink ]; |
| 21 | PA [label = "Other Project\nAuthor/Committer", color=lightblue]; |
| 22 | |
| 23 | === One time setup doc project only === |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 24 | RD -> DA [label = "Acquire Account" ]; |
| 25 | DA -> DR [label = "Create initial\n doc repository content"]; |
| 26 | DA <<-- DR [label = "Merge" ]; |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 27 | RD <-- DA [label = "Connect gerrit.onap.org" ]; |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 28 | === For each project repository containing document source === |
| 29 | PA -> DR [label = "Add project repo as\ngit submodule" ]; |
| 30 | DR -> DA [label = "Review & Plan to\nIntegrate Content with\nTocTree Structure" ]; |
| 31 | DR <-- DA [label = "Vote +2/Merge" ]; |
| 32 | PA <-- DR [label = "Merge Notification" ]; |
| 33 | PA -> PR [label = "Create in project repo\ntop level directory and index.rst" ]; |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 34 | PR -> DA [label = "Add as Reviewer" ]; |
| 35 | PR <-- DA [label = "Approve and Integrate" ]; |
| 36 | PA <-- PR [label = "Merge" ]; |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 37 | } |
| 38 | |
| 39 | |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 40 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 41 | Setup doc project |
| 42 | ----------------- |
| 43 | These steps are performed only once for the doc project and include: |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 44 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 45 | (1) creating in the doc repository an initial: |
| 46 | - sphinx master document index |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 47 | - a directory structure aligned with the document structure |
| 48 | - tests performed in jenkins verify jobs |
| 49 | - sphinx configuration |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 50 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 51 | (2) establishing an account at readthedocs connected with the doc |
| 52 | doc project repo in gerrit.onap.org. |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 53 | |
| 54 | |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 55 | Setup project repositories(s) |
| 56 | ----------------------------- |
| 57 | These steps are performed for each project repository that provides documentation. |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 58 | |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 59 | First let's set two variables that will be used in the subsequent steps. |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 60 | Set reponame to the project repository you are setting up just as it appears in the |
| 61 | **Project Name** column of the Gerrit projects page. |
| 62 | Set lfid to your Linux Foundation identity that you use to login to gerrit or for git |
| 63 | clone requests over ssh. |
| 64 | |
| 65 | .. code-block:: bash |
| 66 | |
| 67 | reponame= |
| 68 | lfid= |
| 69 | |
| 70 | The next step is to add a directory in the doc project where your project will be included as a |
| 71 | submodule and at least one reference from the doc project to the documentation index in your repository. |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 72 | The following sequence will do this over ssh. |
| 73 | |
| 74 | .. caution:: |
| 75 | |
| 76 | If your access network restricts ssh, you will need to use equivalent git commands and |
| 77 | HTTP Passwords as described `here <http://wiki.onap.org/x/X4AP>`_. |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 78 | |
| 79 | .. code-block:: bash |
| 80 | |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 81 | git clone ssh://$lfid@gerrit.onap.org:29418/doc |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 82 | cd doc |
| 83 | mkdir -p `dirname docs/submodules/$reponame` |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 84 | git submodule add https://gerrit.onap.org/r/$reponame docs/submodules/$reponame.git |
| 85 | git submodule init docs/submodules/$reponame.git |
| 86 | git submodule update docs/submodules/$reponame.git |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 87 | |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 88 | echo " $reponame <../submodules/$reponame.git/docs/index>" >> docs/release/repolist.rst |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 89 | |
| 90 | git add . |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 91 | git commit -s |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 92 | git review |
| 93 | |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 94 | .. caution:: |
| 95 | Wait for the above change to be merged before any merge to the |
| 96 | project repository that you have just added as a submodule. |
| 97 | If the project repository added as submodule changes before the doc project merge, git may not |
| 98 | automatically update the submodule reference on changes and/or the verify job will |
| 99 | fail in the step below. |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 100 | |
| 101 | |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 102 | The last step is to create a docs directory in your repository with an index.rst file. |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 103 | The following sequence will complete the minimum required over ssh. As you have time |
| 104 | to convert or add new content you can update the index and add files under the docs folder. |
| 105 | |
| 106 | .. hint:: |
| 107 | If you have additional content, you can include it by editing the |
| 108 | index.rst file and/or adding other files before the git commit. |
| 109 | See `Templates and Examples`_ below and :ref:`converting-to-rst` for more information. |
| 110 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 111 | |
| 112 | .. code-block:: bash |
| 113 | |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 114 | git clone ssh://$lfid@gerrit.onap.org:29418/$reponame |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 115 | cd $reponame |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 116 | mkdir docs |
| 117 | echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License. |
| 118 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 119 | TODO Add files to toctree and delete this header |
| 120 | ------------------------------------------------ |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 121 | .. toctree:: |
| 122 | :maxdepth: 1 |
| 123 | |
| 124 | " > docs/index.rst |
| 125 | |
| 126 | git add . |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 127 | git commit -s |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 128 | git review |
| 129 | |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 130 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 131 | The diagram below illustrates what is accomplished in the setup steps |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 132 | above from the perspective of a file structure created for a local test, |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 133 | a jenkins verify job, and/or published release documentation including: |
jsseidel | da2324a | 2017-09-15 10:43:14 -0400 | [diff] [blame^] | 134 | |
| 135 | - ONAP gerrit project repositories, |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 136 | - doc project repository master document index.rst, templates, configuration, and other documents |
| 137 | - submodules directory where other project repositories and directories/files are referenced |
| 138 | - file structure: directories (ellipses), files(boxes) |
| 139 | - references: directory/files (solid edges), git submodule (dotted edges), sphinx toctree (dashed edges) |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 140 | |
| 141 | |
| 142 | .. graphviz:: |
| 143 | |
| 144 | |
| 145 | digraph docstructure { |
| 146 | size="8,12"; |
| 147 | node [fontname = "helvetica"]; |
| 148 | // Align gerrit repos and docs directories |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 149 | {rank=same doc aaf aai reponame repoelipse vnfsdk vvp} |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 150 | {rank=same confpy release templates masterindex submodules otherdocdocumentelipse} |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 151 | {rank=same releasedocumentindex releaserepolist} |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 152 | |
| 153 | //Illustrate Gerrit Repos and provide URL/Link for complete repo list |
| 154 | gerrit [label="gerrit.onap.org/r", href="https://gerrit.onap.org/r/#/admin/projects/" ]; |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 155 | doc [href="https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree"]; |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 156 | gerrit -> doc; |
| 157 | gerrit -> aaf; |
| 158 | gerrit -> aai; |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 159 | gerrit -> reponame; |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 160 | gerrit -> repoelipse; |
| 161 | repoelipse [label=". . . ."]; |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 162 | gerrit -> vnfsdk; |
| 163 | gerrit -> vvp; |
| 164 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 165 | //Show example of local reponame instance of component info |
| 166 | reponame -> reponamedocsdir; |
| 167 | reponamesm -> reponamedocsdir; |
| 168 | reponamedocsdir [label="docs"]; |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 169 | reponamedocsdir -> repnamedocsdirindex; |
| 170 | repnamedocsdirindex [label="index.rst", shape=box]; |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 171 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 172 | //Show detail structure of a portion of doc/docs |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 173 | doc -> docs; |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 174 | docs -> confpy; |
| 175 | confpy [label="conf.py",shape=box]; |
| 176 | docs -> masterindex; |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 177 | masterindex [label="Master\nindex.rst", shape=box]; |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 178 | docs -> release; |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 179 | docs -> templates; |
| 180 | docs -> otherdocdocumentelipse; |
| 181 | otherdocdocumentelipse [label="...other\ndocuments"]; |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 182 | docs -> submodules |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 183 | |
| 184 | masterindex -> releasedocumentindex [style=dashed, label="sphinx\ntoctree\nreference"]; |
| 185 | |
| 186 | //Show submodule linkage to docs directory |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 187 | submodules -> reponamesm [style=dotted,label="git\nsubmodule\nreference"]; |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 188 | reponamesm [label="reponame.git"]; |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 189 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 190 | //Example Release document index that references component info provided in other project repo |
| 191 | release -> releasedocumentindex; |
| 192 | releasedocumentindex [label="index.rst", shape=box]; |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 193 | releasedocumentindex -> releaserepolist [style=dashed, label="sphinx\ntoctree\nreference"]; |
| 194 | releaserepolist [label="repolist.rst", shape=box]; |
| 195 | release -> releaserepolist; |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 196 | releaserepolist -> repnamedocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"]; |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 197 | |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 198 | } |
| 199 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 200 | Creating Restructured Text |
| 201 | ========================== |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 202 | |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 203 | Templates and Examples |
| 204 | ---------------------- |
| 205 | Some templates are available that capture the kinds of information |
| 206 | useful for different types of projects and provide simple examples of |
| 207 | restructured text. |
| 208 | You can: browse the templates below; show source to look at the Restructured |
| 209 | Text and Sphinx directives used; and then copy the source either from a browser window |
| 210 | or by downloading the file in raw form from |
| 211 | the `gerrit doc repository <https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree;f=docs/templates;/>`_. |
| 212 | |
| 213 | .. toctree:: |
| 214 | :maxdepth: 1 |
| 215 | :glob: |
| 216 | |
| 217 | ../../../templates/**/index |
| 218 | |
| 219 | In addition to these simple templates and examples |
| 220 | there are many open source projects (e.g. Open Daylight, Open Stack) |
| 221 | that are using Sphinx and Readthedocs where you may find examples to start with. |
| 222 | Working with project teams we will continue to enhance templates here and |
| 223 | capture frequently asked questions on the developer wiki question |
| 224 | topic `documentation <https://wiki.onap.org/questions/topics/16384055/documentation>`_. |
| 225 | |
| 226 | Each project should: decide what is relevant content; determine the |
| 227 | best way to create/maintain it in a CI/CD process; and work with the |
| 228 | documentation team to reference content from the master index and guides. |
| 229 | Consider options including filling in a template, |
| 230 | identifying existing content that can be used as is or |
| 231 | easily converted, and use of Sphinx directives/extensions to automatically |
| 232 | generate restructured text from other source you already have. |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 233 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 234 | Links and References |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 235 | -------------------- |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 236 | It's pretty common to want to reference another location in the |
| 237 | ONAP documentation and it's pretty easy to do with |
| 238 | reStructuredText. This is a quick primer, more information is in the |
| 239 | `Sphinx section on Cross-referencing arbitrary locations |
| 240 | <http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_. |
| 241 | |
| 242 | Within a single document, you can reference another section simply by:: |
| 243 | |
| 244 | This is a reference to `The title of a section`_ |
| 245 | |
| 246 | Assuming that somewhere else in the same file there a is a section |
| 247 | title something like:: |
| 248 | |
| 249 | The title of a section |
| 250 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 251 | |
| 252 | It's typically better to use ``:ref:`` syntax and labels to provide |
| 253 | links as they work across files and are resilient to sections being |
| 254 | renamed. First, you need to create a label something like:: |
| 255 | |
| 256 | .. _a-label: |
| 257 | |
| 258 | The title of a section |
| 259 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 260 | |
| 261 | .. note:: The underscore (_) before the label is required. |
| 262 | |
| 263 | Then you can reference the section anywhere by simply doing:: |
| 264 | |
| 265 | This is a reference to :ref:`a-label` |
| 266 | |
| 267 | or:: |
| 268 | |
| 269 | This is a reference to :ref:`a section I really liked <a-label>` |
| 270 | |
| 271 | .. note:: When using ``:ref:``-style links, you don't need a trailing |
| 272 | underscore (_). |
| 273 | |
| 274 | Because the labels have to be unique, it usually makes sense to prefix |
| 275 | the labels with the project name to help share the label space, e.g., |
| 276 | ``sfc-user-guide`` instead of just ``user-guide``. |
| 277 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 278 | Testing |
| 279 | ======= |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 280 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 281 | One RST File |
| 282 | ------------ |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 283 | It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards. |
| 284 | To validate your rst files using doc8, install doc8. |
| 285 | |
| 286 | .. code-block:: bash |
| 287 | |
| 288 | sudo pip install doc8 |
| 289 | |
| 290 | doc8 can now be used to check the rst files. Execute as, |
| 291 | |
| 292 | .. code-block:: bash |
| 293 | |
| 294 | doc8 --ignore D000,D001 <file> |
| 295 | |
| 296 | |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 297 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 298 | One Project |
| 299 | ----------- |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 300 | To test how the documentation renders in HTML, follow these steps: |
| 301 | |
| 302 | Install virtual environment. |
| 303 | |
| 304 | .. code-block:: bash |
| 305 | |
| 306 | sudo pip install virtualenv |
| 307 | cd /local/repo/path/to/project |
| 308 | |
| 309 | Download the doc repository. |
| 310 | |
| 311 | .. code-block:: bash |
| 312 | |
| 313 | git clone http://gerrit.onap.org/r/doc |
| 314 | |
| 315 | Change directory to doc & install requirements. |
| 316 | |
| 317 | .. code-block:: bash |
| 318 | |
| 319 | cd doc |
| 320 | sudo pip install -r etc/requirements.txt |
| 321 | |
| 322 | Move the conf.py file to your project folder where RST files have been kept: |
| 323 | |
| 324 | .. code-block:: bash |
| 325 | |
| 326 | mv doc/docs/conf.py <path-to-your-folder>/ |
| 327 | |
| 328 | Move the static files to your project folder: |
| 329 | |
| 330 | .. code-block:: bash |
| 331 | |
| 332 | mv docs/_static/ <path-to-your-folder>/ |
| 333 | |
| 334 | Build the documentation from within your project folder: |
| 335 | |
| 336 | .. code-block:: bash |
| 337 | |
| 338 | sphinx-build -b html <path-to-your-folder> <path-to-output-folder> |
| 339 | |
| 340 | Your documentation shall be built as HTML inside the |
| 341 | specified output folder directory. |
| 342 | |
| 343 | .. note:: Be sure to remove the `conf.py`, the static/ files and the output folder from the `<project>/docs/`. This is for testing only. Only commit the rst files and related content. |
| 344 | |
| 345 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 346 | All Documentation |
| 347 | ----------------- |
| 348 | To build the whole documentation under doc/, follow these steps: |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 349 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 350 | Install virtual environment. |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 351 | |
| 352 | .. code-block:: bash |
| 353 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 354 | sudo pip install virtualenv |
| 355 | cd /local/repo/path/to/project |
| 356 | |
| 357 | Download the DOC repository. |
| 358 | |
| 359 | .. code-block:: bash |
| 360 | |
| 361 | git clone http://gerrit.onap.org/r/doc |
| 362 | |
| 363 | Change directory to docs & install requirements. |
| 364 | |
| 365 | .. code-block:: bash |
| 366 | |
| 367 | cd doc |
| 368 | sudo pip install -r etc/requirements.txt |
| 369 | |
| 370 | Update submodules, build documentation using tox & then open using any browser. |
| 371 | |
| 372 | .. code-block:: bash |
| 373 | |
| 374 | cd doc |
| 375 | git submodule update --init |
| 376 | tox -edocs |
| 377 | firefox docs/_build/html/index.html |
| 378 | |
| 379 | .. note:: Make sure to run `tox -edocs` and not just `tox`. |
| 380 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 381 | |
| 382 | |