blob: 6ec4ed849e08a21be5b6fdec5a1a986c2e2316b7 [file] [log] [blame]
Rich Bennettac93e0e2017-07-19 01:36:52 -04001.. This work is licensed under a Creative Commons Attribution 4.0 International License.
2
Rich Bennettac93e0e2017-07-19 01:36:52 -04003
Rich Bennett1da30462017-08-24 12:11:36 -04004Setting Up
5==========
jsseidelda2324a2017-09-15 10:43:14 -04006
Rich Bennetta9d6a442017-08-25 02:37:15 -04007Some initial set up is required to connect a project with
Rich Bennett1da30462017-08-24 12:11:36 -04008the master document structure and enable automated publishing of
Rich Bennetta9d6a442017-08-25 02:37:15 -04009changes as summarized in the following diagram and description below
Rich Bennett1da30462017-08-24 12:11:36 -040010below.
Rich Bennettac93e0e2017-07-19 01:36:52 -040011
Rich Bennett1da30462017-08-24 12:11:36 -040012.. seqdiag::
Rich Bennetta9d6a442017-08-25 02:37:15 -040013 :height: 700
14 :width: 1000
Rich Bennettac93e0e2017-07-19 01:36:52 -040015
Rich Bennett1da30462017-08-24 12:11:36 -040016 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 Bennetta9d6a442017-08-25 02:37:15 -040024 RD -> DA [label = "Acquire Account" ];
25 DA -> DR [label = "Create initial\n doc repository content"];
26 DA <<-- DR [label = "Merge" ];
Rich Bennett1da30462017-08-24 12:11:36 -040027 RD <-- DA [label = "Connect gerrit.onap.org" ];
Rich Bennette4c42512017-09-06 08:07:22 -040028 === 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 Bennett358472a2017-08-31 08:05:36 -040034 PR -> DA [label = "Add as Reviewer" ];
35 PR <-- DA [label = "Approve and Integrate" ];
36 PA <-- PR [label = "Merge" ];
Rich Bennett1da30462017-08-24 12:11:36 -040037 }
38
39
Rich Bennettac93e0e2017-07-19 01:36:52 -040040
Rich Bennett1da30462017-08-24 12:11:36 -040041Setup doc project
42-----------------
43These steps are performed only once for the doc project and include:
Rich Bennettac93e0e2017-07-19 01:36:52 -040044
Rich Bennett1da30462017-08-24 12:11:36 -040045(1) creating in the doc repository an initial:
46 - sphinx master document index
Rich Bennetta9d6a442017-08-25 02:37:15 -040047 - a directory structure aligned with the document structure
48 - tests performed in jenkins verify jobs
49 - sphinx configuration
Rich Bennett1da30462017-08-24 12:11:36 -040050
Rich Bennetta9d6a442017-08-25 02:37:15 -040051(2) establishing an account at readthedocs connected with the doc
52doc project repo in gerrit.onap.org.
Rich Bennett1da30462017-08-24 12:11:36 -040053
54
Rich Bennette4c42512017-09-06 08:07:22 -040055Setup project repositories(s)
56-----------------------------
57These steps are performed for each project repository that provides documentation.
Rich Bennett1da30462017-08-24 12:11:36 -040058
Rich Bennett5baea462017-09-13 03:19:19 -040059First let's set two variables that will be used in the subsequent steps.
Rich Bennette4c42512017-09-06 08:07:22 -040060Set reponame to the project repository you are setting up just as it appears in the
61**Project Name** column of the Gerrit projects page.
62Set lfid to your Linux Foundation identity that you use to login to gerrit or for git
63clone requests over ssh.
64
65.. code-block:: bash
66
67 reponame=
68 lfid=
69
70The next step is to add a directory in the doc project where your project will be included as a
71submodule and at least one reference from the doc project to the documentation index in your repository.
Rich Bennett5baea462017-09-13 03:19:19 -040072The 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 Bennett358472a2017-08-31 08:05:36 -040078
79.. code-block:: bash
80
Rich Bennette4c42512017-09-06 08:07:22 -040081 git clone ssh://$lfid@gerrit.onap.org:29418/doc
Rich Bennett358472a2017-08-31 08:05:36 -040082 cd doc
83 mkdir -p `dirname docs/submodules/$reponame`
Rich Bennette4c42512017-09-06 08:07:22 -040084 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 Bennett358472a2017-08-31 08:05:36 -040087
Rich Bennette4c42512017-09-06 08:07:22 -040088 echo " $reponame <../submodules/$reponame.git/docs/index>" >> docs/release/repolist.rst
Rich Bennett358472a2017-08-31 08:05:36 -040089
90 git add .
Rich Bennette4c42512017-09-06 08:07:22 -040091 git commit -s
Rich Bennett358472a2017-08-31 08:05:36 -040092 git review
93
Rich Bennett5baea462017-09-13 03:19:19 -040094.. 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 Bennett358472a2017-08-31 08:05:36 -0400100
101
Rich Bennette4c42512017-09-06 08:07:22 -0400102The last step is to create a docs directory in your repository with an index.rst file.
Rich Bennett5baea462017-09-13 03:19:19 -0400103The following sequence will complete the minimum required over ssh. As you have time
104to 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 Bennett1da30462017-08-24 12:11:36 -0400111
112.. code-block:: bash
113
Rich Bennette4c42512017-09-06 08:07:22 -0400114 git clone ssh://$lfid@gerrit.onap.org:29418/$reponame
Rich Bennetta9d6a442017-08-25 02:37:15 -0400115 cd $reponame
Rich Bennett1da30462017-08-24 12:11:36 -0400116 mkdir docs
117 echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License.
118
Rich Bennetta9d6a442017-08-25 02:37:15 -0400119 TODO Add files to toctree and delete this header
120 ------------------------------------------------
Rich Bennett1da30462017-08-24 12:11:36 -0400121 .. toctree::
122 :maxdepth: 1
123
124 " > docs/index.rst
125
126 git add .
Rich Bennette4c42512017-09-06 08:07:22 -0400127 git commit -s
Rich Bennett1da30462017-08-24 12:11:36 -0400128 git review
129
Rich Bennettac93e0e2017-07-19 01:36:52 -0400130
Rich Bennett1da30462017-08-24 12:11:36 -0400131The diagram below illustrates what is accomplished in the setup steps
Rich Bennetta9d6a442017-08-25 02:37:15 -0400132above from the perspective of a file structure created for a local test,
Rich Bennett358472a2017-08-31 08:05:36 -0400133a jenkins verify job, and/or published release documentation including:
jsseidelda2324a2017-09-15 10:43:14 -0400134
135 - ONAP gerrit project repositories,
Rich Bennett5baea462017-09-13 03:19:19 -0400136 - 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 Bennettac93e0e2017-07-19 01:36:52 -0400140
141
142.. graphviz::
143
144
145 digraph docstructure {
146 size="8,12";
147 node [fontname = "helvetica"];
148 // Align gerrit repos and docs directories
Rich Bennetta9d6a442017-08-25 02:37:15 -0400149 {rank=same doc aaf aai reponame repoelipse vnfsdk vvp}
Rich Bennett1da30462017-08-24 12:11:36 -0400150 {rank=same confpy release templates masterindex submodules otherdocdocumentelipse}
Rich Bennett358472a2017-08-31 08:05:36 -0400151 {rank=same releasedocumentindex releaserepolist}
Rich Bennettac93e0e2017-07-19 01:36:52 -0400152
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 Bennett358472a2017-08-31 08:05:36 -0400155 doc [href="https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree"];
Rich Bennettac93e0e2017-07-19 01:36:52 -0400156 gerrit -> doc;
157 gerrit -> aaf;
158 gerrit -> aai;
Rich Bennetta9d6a442017-08-25 02:37:15 -0400159 gerrit -> reponame;
Rich Bennett1da30462017-08-24 12:11:36 -0400160 gerrit -> repoelipse;
161 repoelipse [label=". . . ."];
Rich Bennettac93e0e2017-07-19 01:36:52 -0400162 gerrit -> vnfsdk;
163 gerrit -> vvp;
164
Rich Bennetta9d6a442017-08-25 02:37:15 -0400165 //Show example of local reponame instance of component info
166 reponame -> reponamedocsdir;
167 reponamesm -> reponamedocsdir;
168 reponamedocsdir [label="docs"];
Rich Bennette4c42512017-09-06 08:07:22 -0400169 reponamedocsdir -> repnamedocsdirindex;
170 repnamedocsdirindex [label="index.rst", shape=box];
Rich Bennettac93e0e2017-07-19 01:36:52 -0400171
Rich Bennett1da30462017-08-24 12:11:36 -0400172 //Show detail structure of a portion of doc/docs
Rich Bennettac93e0e2017-07-19 01:36:52 -0400173 doc -> docs;
Rich Bennett1da30462017-08-24 12:11:36 -0400174 docs -> confpy;
175 confpy [label="conf.py",shape=box];
176 docs -> masterindex;
Rich Bennett358472a2017-08-31 08:05:36 -0400177 masterindex [label="Master\nindex.rst", shape=box];
Rich Bennettac93e0e2017-07-19 01:36:52 -0400178 docs -> release;
Rich Bennett1da30462017-08-24 12:11:36 -0400179 docs -> templates;
180 docs -> otherdocdocumentelipse;
181 otherdocdocumentelipse [label="...other\ndocuments"];
Rich Bennettac93e0e2017-07-19 01:36:52 -0400182 docs -> submodules
Rich Bennett1da30462017-08-24 12:11:36 -0400183
184 masterindex -> releasedocumentindex [style=dashed, label="sphinx\ntoctree\nreference"];
185
186 //Show submodule linkage to docs directory
Rich Bennetta9d6a442017-08-25 02:37:15 -0400187 submodules -> reponamesm [style=dotted,label="git\nsubmodule\nreference"];
Rich Bennette4c42512017-09-06 08:07:22 -0400188 reponamesm [label="reponame.git"];
Rich Bennettac93e0e2017-07-19 01:36:52 -0400189
Rich Bennett1da30462017-08-24 12:11:36 -0400190 //Example Release document index that references component info provided in other project repo
191 release -> releasedocumentindex;
192 releasedocumentindex [label="index.rst", shape=box];
Rich Bennett358472a2017-08-31 08:05:36 -0400193 releasedocumentindex -> releaserepolist [style=dashed, label="sphinx\ntoctree\nreference"];
194 releaserepolist [label="repolist.rst", shape=box];
195 release -> releaserepolist;
Rich Bennette4c42512017-09-06 08:07:22 -0400196 releaserepolist -> repnamedocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"];
Rich Bennett1da30462017-08-24 12:11:36 -0400197
Rich Bennettac93e0e2017-07-19 01:36:52 -0400198 }
199
Rich Bennetta9d6a442017-08-25 02:37:15 -0400200Creating Restructured Text
201==========================
Rich Bennettac93e0e2017-07-19 01:36:52 -0400202
Rich Bennett5baea462017-09-13 03:19:19 -0400203Templates and Examples
204----------------------
205Some templates are available that capture the kinds of information
206useful for different types of projects and provide simple examples of
207restructured text.
208You can: browse the templates below; show source to look at the Restructured
209Text and Sphinx directives used; and then copy the source either from a browser window
210or by downloading the file in raw form from
211the `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
219In addition to these simple templates and examples
220there are many open source projects (e.g. Open Daylight, Open Stack)
221that are using Sphinx and Readthedocs where you may find examples to start with.
222Working with project teams we will continue to enhance templates here and
223capture frequently asked questions on the developer wiki question
224topic `documentation <https://wiki.onap.org/questions/topics/16384055/documentation>`_.
225
226Each project should: decide what is relevant content; determine the
227best way to create/maintain it in a CI/CD process; and work with the
228documentation team to reference content from the master index and guides.
229Consider options including filling in a template,
230identifying existing content that can be used as is or
231easily converted, and use of Sphinx directives/extensions to automatically
232generate restructured text from other source you already have.
Rich Bennettac93e0e2017-07-19 01:36:52 -0400233
Rich Bennetta9d6a442017-08-25 02:37:15 -0400234Links and References
Rich Bennett5baea462017-09-13 03:19:19 -0400235--------------------
Rich Bennettac93e0e2017-07-19 01:36:52 -0400236It's pretty common to want to reference another location in the
237ONAP documentation and it's pretty easy to do with
238reStructuredText. 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
242Within a single document, you can reference another section simply by::
243
244 This is a reference to `The title of a section`_
245
246Assuming that somewhere else in the same file there a is a section
247title something like::
248
249 The title of a section
250 ^^^^^^^^^^^^^^^^^^^^^^
251
252It's typically better to use ``:ref:`` syntax and labels to provide
253links as they work across files and are resilient to sections being
254renamed. 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
263Then you can reference the section anywhere by simply doing::
264
265 This is a reference to :ref:`a-label`
266
267or::
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
274Because the labels have to be unique, it usually makes sense to prefix
275the labels with the project name to help share the label space, e.g.,
276``sfc-user-guide`` instead of just ``user-guide``.
277
Rich Bennetta9d6a442017-08-25 02:37:15 -0400278Testing
279=======
Rich Bennettac93e0e2017-07-19 01:36:52 -0400280
Rich Bennetta9d6a442017-08-25 02:37:15 -0400281One RST File
282------------
Rich Bennettac93e0e2017-07-19 01:36:52 -0400283It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards.
284To validate your rst files using doc8, install doc8.
285
286.. code-block:: bash
287
288 sudo pip install doc8
289
290doc8 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 Bennettac93e0e2017-07-19 01:36:52 -0400297
Rich Bennetta9d6a442017-08-25 02:37:15 -0400298One Project
299-----------
Rich Bennettac93e0e2017-07-19 01:36:52 -0400300To test how the documentation renders in HTML, follow these steps:
301
302Install virtual environment.
303
304.. code-block:: bash
305
306 sudo pip install virtualenv
307 cd /local/repo/path/to/project
308
309Download the doc repository.
310
311.. code-block:: bash
312
313 git clone http://gerrit.onap.org/r/doc
314
315Change directory to doc & install requirements.
316
317.. code-block:: bash
318
319 cd doc
320 sudo pip install -r etc/requirements.txt
321
322Move 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
328Move the static files to your project folder:
329
330.. code-block:: bash
331
332 mv docs/_static/ <path-to-your-folder>/
333
334Build 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
340Your documentation shall be built as HTML inside the
341specified 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 Bennetta9d6a442017-08-25 02:37:15 -0400346All Documentation
347-----------------
348To build the whole documentation under doc/, follow these steps:
Rich Bennettac93e0e2017-07-19 01:36:52 -0400349
Rich Bennetta9d6a442017-08-25 02:37:15 -0400350Install virtual environment.
Rich Bennettac93e0e2017-07-19 01:36:52 -0400351
352.. code-block:: bash
353
Rich Bennetta9d6a442017-08-25 02:37:15 -0400354 sudo pip install virtualenv
355 cd /local/repo/path/to/project
356
357Download the DOC repository.
358
359.. code-block:: bash
360
361 git clone http://gerrit.onap.org/r/doc
362
363Change directory to docs & install requirements.
364
365.. code-block:: bash
366
367 cd doc
368 sudo pip install -r etc/requirements.txt
369
370Update 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 Bennett1da30462017-08-24 12:11:36 -0400381
382