Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 1 | .. This work is licensed under a Creative Commons Attribution 4.0 |
| 2 | .. International License. http://creativecommons.org/licenses/by/4.0 |
| 3 | .. Copyright 2017 AT&T Intellectual Property. All rights reserved. |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 4 | |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 5 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 6 | Setting Up |
| 7 | ========== |
jsseidel | da2324a | 2017-09-15 10:43:14 -0400 | [diff] [blame] | 8 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 9 | Some initial set up is required to connect a project with |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 10 | the master document structure and enable automated publishing of |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 11 | changes as summarized in the following diagram and description below |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 12 | below. |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 13 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 14 | .. seqdiag:: |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 15 | :height: 700 |
| 16 | :width: 1000 |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 17 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 18 | seqdiag { |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 19 | DA [label = "Doc Project\nAuthor/Committer", color=lightblue]; |
| 20 | DR [label = "Doc Gerrit Repo" , color=pink]; |
| 21 | PR [label = "Other Project\nGerrit Repo", color=pink ]; |
| 22 | PA [label = "Other Project\nAuthor/Committer", color=lightblue]; |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 23 | |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 24 | PA -> DR [label = "Add project repo as\ngit submodule" ]; |
| 25 | DR -> DA [label = "Review & Plan to\nIntegrate Content with\nTocTree Structure" ]; |
| 26 | DR <-- DA [label = "Vote +2/Merge" ]; |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 27 | PA <-- DR [label = "Merge Notification" ]; |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 28 | 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] | 29 | PR -> DA [label = "Add as Reviewer" ]; |
| 30 | PR <-- DA [label = "Approve and Integrate" ]; |
| 31 | PA <-- PR [label = "Merge" ]; |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 32 | } |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 33 | |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 34 | Setup project repositories(s) |
| 35 | ----------------------------- |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 36 | These steps are performed for each project repository that |
| 37 | provides documentation. |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 38 | |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 39 | First let's set two variables that will be used in the subsequent steps. |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 40 | Set *reponame* to the project repository you are setting up |
| 41 | just as it appears in the **Project Name** column of |
| 42 | the Gerrit projects page. |
| 43 | Set *lfid* to your Linux Foundation identity that you use to |
| 44 | login to gerrit or for git clone requests over ssh. |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 45 | |
| 46 | .. code-block:: bash |
| 47 | |
| 48 | reponame= |
| 49 | lfid= |
| 50 | |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 51 | The next step is to add a directory in the doc project where your |
| 52 | project will be included as a submodule and at least one reference |
| 53 | from the doc project to the documentation index in your repository. |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 54 | The following sequence will do this over ssh. |
| 55 | |
| 56 | .. caution:: |
| 57 | |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 58 | If your access network restricts ssh, you will need to use equivalent |
| 59 | git commands and HTTP Passwords as described `here <http://wiki.onap.org/x/X4AP>`_. |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 60 | |
Krzysztof Opasiak | 8b43b97 | 2019-05-29 17:29:48 +0200 | [diff] [blame] | 61 | .. caution:: |
| 62 | |
| 63 | Don't replace ../ in *git submodule add* with any relative path on |
| 64 | your local file system. It refers to the location of your repository |
| 65 | on the server. |
| 66 | |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 67 | .. code-block:: bash |
| 68 | |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 69 | git clone ssh://$lfid@gerrit.onap.org:29418/doc |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 70 | cd doc |
| 71 | mkdir -p `dirname docs/submodules/$reponame` |
Rich Bennett | 2360e21 | 2017-09-20 08:26:05 -0400 | [diff] [blame] | 72 | git submodule add ../$reponame docs/submodules/$reponame.git |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 73 | git submodule init docs/submodules/$reponame.git |
| 74 | git submodule update docs/submodules/$reponame.git |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 75 | |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 76 | echo " $reponame <../submodules/$reponame.git/docs/index>" >> docs/release/repolist.rst |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 77 | |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 78 | git add . |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 79 | git commit -s |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 80 | git review |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 81 | |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 82 | .. caution:: |
| 83 | Wait for the above change to be merged before any merge to the |
| 84 | project repository that you have just added as a submodule. |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 85 | If the project repository added as submodule changes before the |
| 86 | doc project merge, git may not automatically update the submodule |
| 87 | reference on changes and/or the verify job will fail in the step below. |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 88 | |
| 89 | |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 90 | The last step is to create a docs directory in your repository with |
| 91 | an index.rst file. The following sequence will complete the minimum |
| 92 | required over ssh. As you have time to convert or add new content you |
| 93 | can update the index and add files under the docs folder. |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 94 | |
| 95 | .. hint:: |
| 96 | If you have additional content, you can include it by editing the |
| 97 | index.rst file and/or adding other files before the git commit. |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 98 | See `Templates and Examples`_ below and :ref:`converting-to-rst` |
| 99 | for more information. |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 100 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 101 | |
| 102 | .. code-block:: bash |
| 103 | |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 104 | git clone ssh://$lfid@gerrit.onap.org:29418/$reponame |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 105 | cd $reponame |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 106 | mkdir docs |
| 107 | echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License. |
| 108 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 109 | TODO Add files to toctree and delete this header |
| 110 | ------------------------------------------------ |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 111 | .. toctree:: |
| 112 | :maxdepth: 1 |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 113 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 114 | " > docs/index.rst |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 115 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 116 | git add . |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 117 | git commit -s |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 118 | git review |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 119 | |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 120 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 121 | The diagram below illustrates what is accomplished in the setup steps |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 122 | 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] | 123 | a jenkins verify job, and/or published release documentation including: |
Rich Bennett | 0c82643 | 2017-09-18 17:28:09 -0400 | [diff] [blame] | 124 | |
| 125 | - ONAP gerrit project repositories, |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 126 | |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 127 | - doc project repository master document index.rst, templates, |
| 128 | configuration, and other documents |
| 129 | |
| 130 | - submodules directory where other project repositories and |
| 131 | directories/files are referenced |
| 132 | |
| 133 | - file structure: directories (ellipses), files(boxes) |
| 134 | |
| 135 | - references: directory/files (solid edges), git submodule |
| 136 | (dotted edges), sphinx toctree (dashed edges) |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 137 | |
| 138 | .. graphviz:: |
| 139 | |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 140 | |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 141 | digraph docstructure { |
| 142 | size="8,12"; |
| 143 | node [fontname = "helvetica"]; |
| 144 | // Align gerrit repos and docs directories |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 145 | {rank=same doc aaf aai reponame repoelipse vnfsdk vvp} |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 146 | {rank=same confpy release templates masterindex submodules otherdocdocumentelipse} |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 147 | {rank=same releasedocumentindex releaserepolist} |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 148 | |
| 149 | //Illustrate Gerrit Repos and provide URL/Link for complete repo list |
| 150 | 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] | 151 | 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] | 152 | gerrit -> doc; |
| 153 | gerrit -> aaf; |
| 154 | gerrit -> aai; |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 155 | gerrit -> reponame; |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 156 | gerrit -> repoelipse; |
| 157 | repoelipse [label=". . . ."]; |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 158 | gerrit -> vnfsdk; |
| 159 | gerrit -> vvp; |
| 160 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 161 | //Show example of local reponame instance of component info |
| 162 | reponame -> reponamedocsdir; |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 163 | reponamesm -> reponamedocsdir; |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 164 | reponamedocsdir [label="docs"]; |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 165 | reponamedocsdir -> repnamedocsdirindex; |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 166 | repnamedocsdirindex [label="index.rst", shape=box]; |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 167 | |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 168 | //Show detail structure of a portion of doc/docs |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 169 | doc -> docs; |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 170 | docs -> confpy; |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 171 | confpy [label="conf.py",shape=box]; |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 172 | docs -> masterindex; |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 173 | masterindex [label="Master\nindex.rst", shape=box]; |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 174 | docs -> release; |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 175 | docs -> templates; |
| 176 | docs -> otherdocdocumentelipse; |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 177 | otherdocdocumentelipse [label="...other\ndocuments"]; |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 178 | docs -> submodules |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 179 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 180 | masterindex -> releasedocumentindex [style=dashed, label="sphinx\ntoctree\nreference"]; |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 181 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 182 | //Show submodule linkage to docs directory |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 183 | submodules -> reponamesm [style=dotted,label="git\nsubmodule\nreference"]; |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 184 | reponamesm [label="reponame.git"]; |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 185 | |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 186 | //Example Release document index that references component info provided in other project repo |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 187 | release -> releasedocumentindex; |
Rich Bennett | 1da3046 | 2017-08-24 12:11:36 -0400 | [diff] [blame] | 188 | releasedocumentindex [label="index.rst", shape=box]; |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 189 | releasedocumentindex -> releaserepolist [style=dashed, label="sphinx\ntoctree\nreference"]; |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 190 | releaserepolist [label="repolist.rst", shape=box]; |
Rich Bennett | 358472a | 2017-08-31 08:05:36 -0400 | [diff] [blame] | 191 | release -> releaserepolist; |
Rich Bennett | e4c4251 | 2017-09-06 08:07:22 -0400 | [diff] [blame] | 192 | releaserepolist -> repnamedocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"]; |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 193 | |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 194 | } |
| 195 | |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 196 | Branches in the DOC Project |
| 197 | --------------------------- |
| 198 | |
| 199 | The DOC project 'master' branch aggregates the 'latest' content |
| 200 | from all ONAP project repositories contributing documentation into a |
| 201 | single tree file structure as described in the previous section. This |
| 202 | branch is continuously integrated and deployed at Read The |
| 203 | Docs as the 'latest' ONAP Documentation by: |
| 204 | |
| 205 | * Jenkins doc-verify-rtd and doc-merge-rtd jobs triggered whenever patches on |
| 206 | contributing repositories contain rst files at or below a top level |
| 207 | 'docs' folder. |
| 208 | |
| 209 | * Subscription in the DOC project to changes in submodule repositories. |
| 210 | These changes appear in the DOC project as commits with title |
| 211 | 'Updated git submodules' when a change to a contributing project |
| 212 | repository is merged. No DOC project code review occurs, only a |
| 213 | submodule repository commit hash is updated to track the head of each |
| 214 | contributing master branch. |
| 215 | |
| 216 | For each ONAP named release the DOC project creates a branch with the |
| 217 | release name. The timing of the release branch is determined by |
| 218 | work needed in the DOC project to prepare the release branch and the |
| 219 | amount of change unrelated to the release in the master branch. |
| 220 | For example contributing projects that create named release branches |
| 221 | early to begin work on the next release and/or contributing projects |
| 222 | to the master that are not yet part of the named release would result |
| 223 | in an earlier named release branch to cleanly separate work to stabilize |
| 224 | a release from other changes in the master branch. |
| 225 | |
| 226 | A named release branch is integrated and deployed at Read The Docs |
| 227 | as the 'named release' by aggregating content from contributing |
| 228 | project repositories. A contributing project repository can |
| 229 | choose one of the following for the 'named release' branch: |
| 230 | |
| 231 | * Remove the contributing project repository submodule and RST |
| 232 | references when not part of the named release. |
| 233 | |
| 234 | * Provide a commit hash or tag for the contributing project master |
| 235 | branch to be used for the life of the release branch or until a |
| 236 | request is submitted to change the commit hash or tag. |
| 237 | |
| 238 | * Provide the commit hash for the head of a named release branch |
| 239 | created in the contributing project repository. This option |
| 240 | may be appropriate if frequent changes are expected over the |
| 241 | life of the named release and work the same way as the continuous |
| 242 | integration and deployment described for the master branch. |
| 243 | |
| 244 | The decision on option for each contributing project repository |
| 245 | can be made or changed before the final release is approved. The |
| 246 | amount of change and expected differences between master and a |
| 247 | named release branch for each repository should drive the choice of |
| 248 | option and timing. |
| 249 | |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 250 | About GIT branches |
| 251 | ------------------ |
| 252 | |
| 253 | GIT is a powerful tool allowing many actions, but without respecting some rules |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 254 | the GIT structure can be quickly hard to maintain. |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 255 | |
| 256 | Here are some conventions about GIT branches: |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 257 | |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 258 | - ALWAYS create a local branch to edit or create any file. This local branch |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 259 | will be considered as a topic in Gerrit and allow contributors to |
| 260 | work at the same time on the same project. |
| 261 | |
| 262 | - 1 feature = 1 branch. In the case of documentation, a new chapter |
| 263 | or page about a new code feature can be considered as a 'doc feature' |
| 264 | |
| 265 | - 1 bug = 1 branch. In the case of documentation, a correction on an |
| 266 | existing sentence can be considered as a 'doc bug' |
| 267 | |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 268 | - the master branch is considered as "unstable", containing new features that |
| 269 | will converge to a stable situation for the release date. |
| 270 | |
| 271 | The day of the release, the repository owner will create a new branch to |
| 272 | fix the code and documentation. This will represent the 'stable' code of the |
| 273 | release. In this context: |
Rich Bennett | 7e34ab3 | 2018-04-18 11:03:25 -0400 | [diff] [blame] | 274 | |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 275 | - NEVER push a new feature on a stable branch |
Rich Bennett | 7e34ab3 | 2018-04-18 11:03:25 -0400 | [diff] [blame] | 276 | |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 277 | - Only bug correction are authorized on a stable branch using |
| 278 | cherry pick method |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 279 | |
| 280 | .. image:: git_branches.png |
| 281 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 282 | Creating Restructured Text |
| 283 | ========================== |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 284 | |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 285 | Templates and Examples |
| 286 | ---------------------- |
Rich Bennett | 7134cba | 2017-10-10 07:39:06 -0400 | [diff] [blame] | 287 | Templates are available that capture the kinds of information |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 288 | useful for different types of projects and provide some examples of |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 289 | restructured text. We organize templates in the following way to: |
Rich Bennett | 7134cba | 2017-10-10 07:39:06 -0400 | [diff] [blame] | 290 | |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 291 | - help authors understand relationships between documents |
| 292 | |
| 293 | - keep the user audience context in mind when writing and |
| 294 | |
| 295 | - tailor sections for different kinds of projects. |
| 296 | |
| 297 | |
| 298 | **Sections** Represent a certain type of content. A section |
| 299 | is **provided** in an project repository, to describe something about |
| 300 | the characteristics, use, capability, etc. of things in that repository. |
| 301 | A section may also be **referenced** from other sections and in |
| 302 | other repositories. For example, an API specification provided in a project |
| 303 | repository might be referenced to in a Platform API Reference Guide. |
Rich Bennett | 7134cba | 2017-10-10 07:39:06 -0400 | [diff] [blame] | 304 | The notes in the beginning of each section template provide |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 305 | additional detail about what is typically covered and where |
| 306 | there may be references to the section. |
Rich Bennett | 7134cba | 2017-10-10 07:39:06 -0400 | [diff] [blame] | 307 | |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 308 | **Collections** Are a set of sections that are typically provided |
| 309 | for a particular type of project, repository, guide, reference manual, etc. |
| 310 | For example, a collection for a platform component, an SDK, etc. |
Rich Bennett | 7134cba | 2017-10-10 07:39:06 -0400 | [diff] [blame] | 311 | |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 312 | You can: browse the template *collections* and *sections* below; |
| 313 | show source to look at the Restructured Text and Sphinx directives used; |
| 314 | copy the source either from a browser window or by downloading the |
| 315 | file in raw form from |
Rich Bennett | 7134cba | 2017-10-10 07:39:06 -0400 | [diff] [blame] | 316 | the `gerrit doc repository <https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree;f=docs/templates;/>`_ and |
| 317 | then add them to your repository docs folder and index.rst. |
| 318 | |
| 319 | |
| 320 | Sections |
| 321 | ++++++++ |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 322 | |
| 323 | .. toctree:: |
| 324 | :maxdepth: 1 |
| 325 | :glob: |
| 326 | |
Rich Bennett | 7134cba | 2017-10-10 07:39:06 -0400 | [diff] [blame] | 327 | ../../../templates/sections/* |
| 328 | |
| 329 | |
| 330 | Collections |
| 331 | +++++++++++ |
| 332 | |
| 333 | .. toctree:: |
| 334 | :maxdepth: 1 |
| 335 | :glob: |
| 336 | |
| 337 | ../../../templates/collections/* |
| 338 | |
| 339 | |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 340 | |
Blaisonneau David | 2963ece | 2017-11-27 10:07:18 +0100 | [diff] [blame] | 341 | In addition to these simple templates and examples |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 342 | there are many open source projects (e.g. Open Daylight, Open Stack) |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 343 | that are using Sphinx and Readthedocs where you may find examples |
| 344 | to start with. Working with project teams we will continue to enhance |
| 345 | templates here and capture frequently asked questions on the developer |
| 346 | wiki question topic `documentation <https://wiki.onap.org/questions/topics/16384055/documentation>`_. |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 347 | |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 348 | Each project should: |
| 349 | |
| 350 | - decide what is relevant content |
| 351 | |
| 352 | - determine the best way to create/maintain it in the CI/CD process and |
| 353 | |
| 354 | - work with the documentation team to reference content from the |
| 355 | master index and guides. |
| 356 | |
| 357 | Consider options including filling in a template, identifying existing |
| 358 | content that can be used as is or easily converted, and use of Sphinx |
| 359 | directives/extensions to automatically generate restructured text |
| 360 | from other source you already have. |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 361 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 362 | Links and References |
Rich Bennett | 5baea46 | 2017-09-13 03:19:19 -0400 | [diff] [blame] | 363 | -------------------- |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 364 | It's pretty common to want to reference another location in the |
| 365 | ONAP documentation and it's pretty easy to do with |
| 366 | reStructuredText. This is a quick primer, more information is in the |
| 367 | `Sphinx section on Cross-referencing arbitrary locations |
| 368 | <http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_. |
| 369 | |
| 370 | Within a single document, you can reference another section simply by:: |
| 371 | |
| 372 | This is a reference to `The title of a section`_ |
| 373 | |
| 374 | Assuming that somewhere else in the same file there a is a section |
| 375 | title something like:: |
| 376 | |
| 377 | The title of a section |
| 378 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 379 | |
| 380 | It's typically better to use ``:ref:`` syntax and labels to provide |
| 381 | links as they work across files and are resilient to sections being |
| 382 | renamed. First, you need to create a label something like:: |
| 383 | |
| 384 | .. _a-label: |
| 385 | |
| 386 | The title of a section |
| 387 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 388 | |
| 389 | .. note:: The underscore (_) before the label is required. |
| 390 | |
| 391 | Then you can reference the section anywhere by simply doing:: |
| 392 | |
| 393 | This is a reference to :ref:`a-label` |
| 394 | |
| 395 | or:: |
| 396 | |
| 397 | This is a reference to :ref:`a section I really liked <a-label>` |
| 398 | |
| 399 | .. note:: When using ``:ref:``-style links, you don't need a trailing |
| 400 | underscore (_). |
| 401 | |
| 402 | Because the labels have to be unique, it usually makes sense to prefix |
| 403 | the labels with the project name to help share the label space, e.g., |
| 404 | ``sfc-user-guide`` instead of just ``user-guide``. |
| 405 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 406 | Testing |
| 407 | ======= |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 408 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 409 | One RST File |
| 410 | ------------ |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 411 | It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards. |
| 412 | To validate your rst files using doc8, install doc8. |
| 413 | |
| 414 | .. code-block:: bash |
| 415 | |
| 416 | sudo pip install doc8 |
| 417 | |
| 418 | doc8 can now be used to check the rst files. Execute as, |
| 419 | |
| 420 | .. code-block:: bash |
| 421 | |
| 422 | doc8 --ignore D000,D001 <file> |
| 423 | |
| 424 | |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 425 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 426 | One Project |
| 427 | ----------- |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 428 | To test how the documentation renders in HTML, follow these steps: |
| 429 | |
Pawel Wieczorek | 1a3294f | 2019-07-10 16:20:22 +0200 | [diff] [blame] | 430 | Install `virtual environment <https://pypi.org/project/virtualenv>`_ & create one. |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 431 | |
| 432 | .. code-block:: bash |
| 433 | |
| 434 | sudo pip install virtualenv |
Pawel Wieczorek | 1a3294f | 2019-07-10 16:20:22 +0200 | [diff] [blame] | 435 | virtualenv onap_docs |
| 436 | |
| 437 | Activate `onap_docs` virtual environment. |
| 438 | |
| 439 | .. code-block:: bash |
| 440 | |
| 441 | source onap_docs/bin/activate |
| 442 | |
| 443 | .. note:: Virtual environment activation has to be performed before attempting to build documentation. |
| 444 | Otherwise, tools necessary for the process might not be available. |
Rene_Robert | bf4ab4e | 2019-07-01 18:12:40 +0200 | [diff] [blame] | 445 | |
| 446 | Download a project repository. |
| 447 | |
| 448 | .. code-block:: bash |
| 449 | |
Pawel Wieczorek | 1a3294f | 2019-07-10 16:20:22 +0200 | [diff] [blame] | 450 | git clone http://gerrit.onap.org/r/<project> |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 451 | |
| 452 | Download the doc repository. |
| 453 | |
| 454 | .. code-block:: bash |
| 455 | |
| 456 | git clone http://gerrit.onap.org/r/doc |
| 457 | |
| 458 | Change directory to doc & install requirements. |
| 459 | |
| 460 | .. code-block:: bash |
| 461 | |
| 462 | cd doc |
Pawel Wieczorek | 1a3294f | 2019-07-10 16:20:22 +0200 | [diff] [blame] | 463 | pip install -r etc/requirements.txt |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 464 | |
Rene_Robert | bf4ab4e | 2019-07-01 18:12:40 +0200 | [diff] [blame] | 465 | Copy the conf.py file to your project folder where RST files have been kept: |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 466 | |
| 467 | .. code-block:: bash |
| 468 | |
Rene_Robert | bf4ab4e | 2019-07-01 18:12:40 +0200 | [diff] [blame] | 469 | cp docs/conf.py <path-to-project-folder>/<folder where are rst files> |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 470 | |
Rene_Robert | bf4ab4e | 2019-07-01 18:12:40 +0200 | [diff] [blame] | 471 | Copy the static files to the project folder where RST files have been kept: |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 472 | |
| 473 | .. code-block:: bash |
| 474 | |
Rene_Robert | bf4ab4e | 2019-07-01 18:12:40 +0200 | [diff] [blame] | 475 | cp -r docs/_static/ <path-to-project-folder>/<folder where are rst files> |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 476 | |
| 477 | Build the documentation from within your project folder: |
| 478 | |
| 479 | .. code-block:: bash |
| 480 | |
Rene_Robert | bf4ab4e | 2019-07-01 18:12:40 +0200 | [diff] [blame] | 481 | sphinx-build -b html <path-to-project-folder>/<folder where are rst files> <path-to-output-folder> |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 482 | |
| 483 | Your documentation shall be built as HTML inside the |
| 484 | specified output folder directory. |
| 485 | |
Rene_Robert | bf4ab4e | 2019-07-01 18:12:40 +0200 | [diff] [blame] | 486 | You can use your Web Browser to open |
| 487 | and check resulting html pages in the output folder. |
| 488 | |
Pawel Wieczorek | 1a3294f | 2019-07-10 16:20:22 +0200 | [diff] [blame] | 489 | .. 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. |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 490 | |
jsseidel | 8066619 | 2017-09-19 13:29:23 -0400 | [diff] [blame] | 491 | .. _building-all-documentation: |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 492 | |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 493 | All Documentation |
| 494 | ----------------- |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 495 | To build the all documentation under doc/, follow these steps: |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 496 | |
Pawel Wieczorek | 6e82383 | 2019-07-10 16:31:27 +0200 | [diff] [blame^] | 497 | Install `tox <https://pypi.org/project/tox>`_. |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 498 | |
| 499 | .. code-block:: bash |
| 500 | |
Pawel Wieczorek | 6e82383 | 2019-07-10 16:31:27 +0200 | [diff] [blame^] | 501 | sudo pip install tox |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 502 | |
| 503 | Download the DOC repository. |
| 504 | |
| 505 | .. code-block:: bash |
| 506 | |
| 507 | git clone http://gerrit.onap.org/r/doc |
| 508 | |
Rich Bennett | 9c3af50 | 2018-04-26 09:30:57 -0400 | [diff] [blame] | 509 | Build documentation using tox local environment & then open using any browser. |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 510 | |
| 511 | .. code-block:: bash |
| 512 | |
| 513 | cd doc |
Cédric Ollivier | 268209c | 2017-11-10 11:31:53 +0100 | [diff] [blame] | 514 | tox -elocal |
Rich Bennett | a9d6a44 | 2017-08-25 02:37:15 -0400 | [diff] [blame] | 515 | firefox docs/_build/html/index.html |
| 516 | |
Cédric Ollivier | 268209c | 2017-11-10 11:31:53 +0100 | [diff] [blame] | 517 | .. note:: Make sure to run `tox -elocal` and not just `tox`. |
Rich Bennett | 50d0d88 | 2019-03-08 17:03:58 -0500 | [diff] [blame] | 518 | This updates all submodule repositories that are integrated |
| 519 | by the doc project. |
Rich Bennett | 9c3af50 | 2018-04-26 09:30:57 -0400 | [diff] [blame] | 520 | |
Rich Bennett | d504dc8 | 2018-05-31 08:40:36 -0400 | [diff] [blame] | 521 | There are additional tox environment options for checking External |
Rene_Robert | bf4ab4e | 2019-07-01 18:12:40 +0200 | [diff] [blame] | 522 | URLs and Spelling. Use the tox environment options below and then |
Rich Bennett | 50d0d88 | 2019-03-08 17:03:58 -0500 | [diff] [blame] | 523 | look at the output with the Linux `more` or similar command |
| 524 | scan for output that applies to the files you are validating. |
Rich Bennett | 9c3af50 | 2018-04-26 09:30:57 -0400 | [diff] [blame] | 525 | |
| 526 | .. code-block:: bash |
| 527 | |
| 528 | tox -elinkcheck |
| 529 | more < docs/_build/linkcheck/output.txt |
| 530 | |
| 531 | tox -espellcheck |
| 532 | more < docs/_build/spellcheck/output.txt |