blob: 97a9d7356edf0f40d71dbeba0d0b7b968d0b1dbe [file] [log] [blame]
Rich Bennettd504dc82018-05-31 08:40:36 -04001.. 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 Bennettac93e0e2017-07-19 01:36:52 -04004
Rich Bennettac93e0e2017-07-19 01:36:52 -04005
Rich Bennett1da30462017-08-24 12:11:36 -04006Setting Up
7==========
jsseidelda2324a2017-09-15 10:43:14 -04008
Rich Bennetta9d6a442017-08-25 02:37:15 -04009Some initial set up is required to connect a project with
Rich Bennett1da30462017-08-24 12:11:36 -040010the master document structure and enable automated publishing of
Blaisonneau David2963ece2017-11-27 10:07:18 +010011changes as summarized in the following diagram and description below
Rich Bennett1da30462017-08-24 12:11:36 -040012below.
Rich Bennettac93e0e2017-07-19 01:36:52 -040013
Rich Bennett1da30462017-08-24 12:11:36 -040014.. seqdiag::
Rich Bennetta9d6a442017-08-25 02:37:15 -040015 :height: 700
16 :width: 1000
Rich Bennettac93e0e2017-07-19 01:36:52 -040017
Rich Bennett1da30462017-08-24 12:11:36 -040018 seqdiag {
Rich Bennett1da30462017-08-24 12:11:36 -040019 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 David2963ece2017-11-27 10:07:18 +010023
Rich Bennette4c42512017-09-06 08:07:22 -040024 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 David2963ece2017-11-27 10:07:18 +010027 PA <-- DR [label = "Merge Notification" ];
Rich Bennette4c42512017-09-06 08:07:22 -040028 PA -> PR [label = "Create in project repo\ntop level directory and index.rst" ];
Rich Bennett358472a2017-08-31 08:05:36 -040029 PR -> DA [label = "Add as Reviewer" ];
30 PR <-- DA [label = "Approve and Integrate" ];
31 PA <-- PR [label = "Merge" ];
Rich Bennett1da30462017-08-24 12:11:36 -040032 }
Blaisonneau David2963ece2017-11-27 10:07:18 +010033
Rich Bennette4c42512017-09-06 08:07:22 -040034Setup project repositories(s)
35-----------------------------
Rich Bennettd504dc82018-05-31 08:40:36 -040036These steps are performed for each project repository that
37provides documentation.
Rich Bennett1da30462017-08-24 12:11:36 -040038
Rich Bennett5baea462017-09-13 03:19:19 -040039First let's set two variables that will be used in the subsequent steps.
Rich Bennettd504dc82018-05-31 08:40:36 -040040Set *reponame* to the project repository you are setting up
41just as it appears in the **Project Name** column of
42the Gerrit projects page.
43Set *lfid* to your Linux Foundation identity that you use to
44login to gerrit or for git clone requests over ssh.
Rich Bennette4c42512017-09-06 08:07:22 -040045
46.. code-block:: bash
47
48 reponame=
49 lfid=
50
Rich Bennettd504dc82018-05-31 08:40:36 -040051The next step is to add a directory in the doc project where your
52project will be included as a submodule and at least one reference
53from the doc project to the documentation index in your repository.
Rich Bennett5baea462017-09-13 03:19:19 -040054The following sequence will do this over ssh.
55
56.. caution::
57
Rich Bennettd504dc82018-05-31 08:40:36 -040058 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 David2963ece2017-11-27 10:07:18 +010060
Krzysztof Opasiak8b43b972019-05-29 17:29:48 +020061.. 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 Bennett358472a2017-08-31 08:05:36 -040067.. code-block:: bash
68
Rich Bennette4c42512017-09-06 08:07:22 -040069 git clone ssh://$lfid@gerrit.onap.org:29418/doc
Rich Bennett358472a2017-08-31 08:05:36 -040070 cd doc
71 mkdir -p `dirname docs/submodules/$reponame`
Rich Bennett2360e212017-09-20 08:26:05 -040072 git submodule add ../$reponame docs/submodules/$reponame.git
Rich Bennette4c42512017-09-06 08:07:22 -040073 git submodule init docs/submodules/$reponame.git
74 git submodule update docs/submodules/$reponame.git
Rich Bennett358472a2017-08-31 08:05:36 -040075
Rich Bennette4c42512017-09-06 08:07:22 -040076 echo " $reponame <../submodules/$reponame.git/docs/index>" >> docs/release/repolist.rst
Blaisonneau David2963ece2017-11-27 10:07:18 +010077
Rich Bennett358472a2017-08-31 08:05:36 -040078 git add .
Rich Bennette4c42512017-09-06 08:07:22 -040079 git commit -s
Rich Bennett358472a2017-08-31 08:05:36 -040080 git review
Blaisonneau David2963ece2017-11-27 10:07:18 +010081
Rich Bennett5baea462017-09-13 03:19:19 -040082.. 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 Bennettd504dc82018-05-31 08:40:36 -040085 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 Bennett358472a2017-08-31 08:05:36 -040088
89
Rich Bennettd504dc82018-05-31 08:40:36 -040090The last step is to create a docs directory in your repository with
91an index.rst file. The following sequence will complete the minimum
92required over ssh. As you have time to convert or add new content you
93can update the index and add files under the docs folder.
Rich Bennett5baea462017-09-13 03:19:19 -040094
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 Bennettd504dc82018-05-31 08:40:36 -040098 See `Templates and Examples`_ below and :ref:`converting-to-rst`
99 for more information.
Blaisonneau David2963ece2017-11-27 10:07:18 +0100100
Rich Bennett1da30462017-08-24 12:11:36 -0400101
102.. code-block:: bash
103
Rich Bennette4c42512017-09-06 08:07:22 -0400104 git clone ssh://$lfid@gerrit.onap.org:29418/$reponame
Rich Bennetta9d6a442017-08-25 02:37:15 -0400105 cd $reponame
Rich Bennett1da30462017-08-24 12:11:36 -0400106 mkdir docs
107 echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License.
108
Rich Bennetta9d6a442017-08-25 02:37:15 -0400109 TODO Add files to toctree and delete this header
110 ------------------------------------------------
Rich Bennett1da30462017-08-24 12:11:36 -0400111 .. toctree::
112 :maxdepth: 1
Blaisonneau David2963ece2017-11-27 10:07:18 +0100113
Rich Bennett1da30462017-08-24 12:11:36 -0400114 " > docs/index.rst
Blaisonneau David2963ece2017-11-27 10:07:18 +0100115
Rich Bennett1da30462017-08-24 12:11:36 -0400116 git add .
Rich Bennette4c42512017-09-06 08:07:22 -0400117 git commit -s
Rich Bennett1da30462017-08-24 12:11:36 -0400118 git review
Blaisonneau David2963ece2017-11-27 10:07:18 +0100119
Rich Bennettac93e0e2017-07-19 01:36:52 -0400120
Rich Bennett1da30462017-08-24 12:11:36 -0400121The diagram below illustrates what is accomplished in the setup steps
Rich Bennetta9d6a442017-08-25 02:37:15 -0400122above from the perspective of a file structure created for a local test,
Rich Bennett358472a2017-08-31 08:05:36 -0400123a jenkins verify job, and/or published release documentation including:
Rich Bennett0c826432017-09-18 17:28:09 -0400124
125- ONAP gerrit project repositories,
Rich Bennettac93e0e2017-07-19 01:36:52 -0400126
Rich Bennettd504dc82018-05-31 08:40:36 -0400127- 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 Bennettac93e0e2017-07-19 01:36:52 -0400137
138.. graphviz::
139
Blaisonneau David2963ece2017-11-27 10:07:18 +0100140
Rich Bennettac93e0e2017-07-19 01:36:52 -0400141 digraph docstructure {
142 size="8,12";
143 node [fontname = "helvetica"];
144 // Align gerrit repos and docs directories
Rich Bennetta9d6a442017-08-25 02:37:15 -0400145 {rank=same doc aaf aai reponame repoelipse vnfsdk vvp}
Rich Bennett1da30462017-08-24 12:11:36 -0400146 {rank=same confpy release templates masterindex submodules otherdocdocumentelipse}
Rich Bennett358472a2017-08-31 08:05:36 -0400147 {rank=same releasedocumentindex releaserepolist}
Rich Bennettac93e0e2017-07-19 01:36:52 -0400148
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 Bennett358472a2017-08-31 08:05:36 -0400151 doc [href="https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree"];
Rich Bennettac93e0e2017-07-19 01:36:52 -0400152 gerrit -> doc;
153 gerrit -> aaf;
154 gerrit -> aai;
Blaisonneau David2963ece2017-11-27 10:07:18 +0100155 gerrit -> reponame;
Rich Bennett1da30462017-08-24 12:11:36 -0400156 gerrit -> repoelipse;
157 repoelipse [label=". . . ."];
Rich Bennettac93e0e2017-07-19 01:36:52 -0400158 gerrit -> vnfsdk;
159 gerrit -> vvp;
160
Rich Bennetta9d6a442017-08-25 02:37:15 -0400161 //Show example of local reponame instance of component info
162 reponame -> reponamedocsdir;
Blaisonneau David2963ece2017-11-27 10:07:18 +0100163 reponamesm -> reponamedocsdir;
Rich Bennetta9d6a442017-08-25 02:37:15 -0400164 reponamedocsdir [label="docs"];
Blaisonneau David2963ece2017-11-27 10:07:18 +0100165 reponamedocsdir -> repnamedocsdirindex;
Rich Bennette4c42512017-09-06 08:07:22 -0400166 repnamedocsdirindex [label="index.rst", shape=box];
Rich Bennettac93e0e2017-07-19 01:36:52 -0400167
Blaisonneau David2963ece2017-11-27 10:07:18 +0100168 //Show detail structure of a portion of doc/docs
Rich Bennettac93e0e2017-07-19 01:36:52 -0400169 doc -> docs;
Blaisonneau David2963ece2017-11-27 10:07:18 +0100170 docs -> confpy;
Rich Bennett1da30462017-08-24 12:11:36 -0400171 confpy [label="conf.py",shape=box];
Blaisonneau David2963ece2017-11-27 10:07:18 +0100172 docs -> masterindex;
Rich Bennett358472a2017-08-31 08:05:36 -0400173 masterindex [label="Master\nindex.rst", shape=box];
Rich Bennettac93e0e2017-07-19 01:36:52 -0400174 docs -> release;
Blaisonneau David2963ece2017-11-27 10:07:18 +0100175 docs -> templates;
176 docs -> otherdocdocumentelipse;
Rich Bennett1da30462017-08-24 12:11:36 -0400177 otherdocdocumentelipse [label="...other\ndocuments"];
Rich Bennettac93e0e2017-07-19 01:36:52 -0400178 docs -> submodules
Blaisonneau David2963ece2017-11-27 10:07:18 +0100179
Rich Bennett1da30462017-08-24 12:11:36 -0400180 masterindex -> releasedocumentindex [style=dashed, label="sphinx\ntoctree\nreference"];
Blaisonneau David2963ece2017-11-27 10:07:18 +0100181
Rich Bennett1da30462017-08-24 12:11:36 -0400182 //Show submodule linkage to docs directory
Blaisonneau David2963ece2017-11-27 10:07:18 +0100183 submodules -> reponamesm [style=dotted,label="git\nsubmodule\nreference"];
Rich Bennette4c42512017-09-06 08:07:22 -0400184 reponamesm [label="reponame.git"];
Rich Bennettac93e0e2017-07-19 01:36:52 -0400185
Rich Bennett1da30462017-08-24 12:11:36 -0400186 //Example Release document index that references component info provided in other project repo
Blaisonneau David2963ece2017-11-27 10:07:18 +0100187 release -> releasedocumentindex;
Rich Bennett1da30462017-08-24 12:11:36 -0400188 releasedocumentindex [label="index.rst", shape=box];
Rich Bennett358472a2017-08-31 08:05:36 -0400189 releasedocumentindex -> releaserepolist [style=dashed, label="sphinx\ntoctree\nreference"];
Blaisonneau David2963ece2017-11-27 10:07:18 +0100190 releaserepolist [label="repolist.rst", shape=box];
Rich Bennett358472a2017-08-31 08:05:36 -0400191 release -> releaserepolist;
Rich Bennette4c42512017-09-06 08:07:22 -0400192 releaserepolist -> repnamedocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"];
Blaisonneau David2963ece2017-11-27 10:07:18 +0100193
Rich Bennettac93e0e2017-07-19 01:36:52 -0400194 }
195
Rich Bennettd504dc82018-05-31 08:40:36 -0400196Branches in the DOC Project
197---------------------------
198
199The DOC project 'master' branch aggregates the 'latest' content
200from all ONAP project repositories contributing documentation into a
201single tree file structure as described in the previous section. This
202branch is continuously integrated and deployed at Read The
203Docs 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
216For each ONAP named release the DOC project creates a branch with the
217release name. The timing of the release branch is determined by
218work needed in the DOC project to prepare the release branch and the
219amount of change unrelated to the release in the master branch.
220For example contributing projects that create named release branches
221early to begin work on the next release and/or contributing projects
222to the master that are not yet part of the named release would result
223in an earlier named release branch to cleanly separate work to stabilize
224a release from other changes in the master branch.
225
226A named release branch is integrated and deployed at Read The Docs
227as the 'named release' by aggregating content from contributing
228project repositories. A contributing project repository can
229choose 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
244The decision on option for each contributing project repository
245can be made or changed before the final release is approved. The
246amount of change and expected differences between master and a
247named release branch for each repository should drive the choice of
248option and timing.
249
Blaisonneau David2963ece2017-11-27 10:07:18 +0100250About GIT branches
251------------------
252
253GIT is a powerful tool allowing many actions, but without respecting some rules
Rich Bennettd504dc82018-05-31 08:40:36 -0400254the GIT structure can be quickly hard to maintain.
Blaisonneau David2963ece2017-11-27 10:07:18 +0100255
256Here are some conventions about GIT branches:
Rich Bennettd504dc82018-05-31 08:40:36 -0400257
Blaisonneau David2963ece2017-11-27 10:07:18 +0100258 - ALWAYS create a local branch to edit or create any file. This local branch
Rich Bennettd504dc82018-05-31 08:40:36 -0400259 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 David2963ece2017-11-27 10:07:18 +0100268 - the master branch is considered as "unstable", containing new features that
269 will converge to a stable situation for the release date.
270
271The day of the release, the repository owner will create a new branch to
272fix the code and documentation. This will represent the 'stable' code of the
273release. In this context:
Rich Bennett7e34ab32018-04-18 11:03:25 -0400274
Blaisonneau David2963ece2017-11-27 10:07:18 +0100275 - NEVER push a new feature on a stable branch
Rich Bennett7e34ab32018-04-18 11:03:25 -0400276
Rich Bennettd504dc82018-05-31 08:40:36 -0400277 - Only bug correction are authorized on a stable branch using
278 cherry pick method
Blaisonneau David2963ece2017-11-27 10:07:18 +0100279
280.. image:: git_branches.png
281
Rich Bennetta9d6a442017-08-25 02:37:15 -0400282Creating Restructured Text
283==========================
Rich Bennettac93e0e2017-07-19 01:36:52 -0400284
Rich Bennett5baea462017-09-13 03:19:19 -0400285Templates and Examples
286----------------------
Rich Bennett7134cba2017-10-10 07:39:06 -0400287Templates are available that capture the kinds of information
Blaisonneau David2963ece2017-11-27 10:07:18 +0100288useful for different types of projects and provide some examples of
Rich Bennettd504dc82018-05-31 08:40:36 -0400289restructured text. We organize templates in the following way to:
Rich Bennett7134cba2017-10-10 07:39:06 -0400290
Rich Bennettd504dc82018-05-31 08:40:36 -0400291 - 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
299is **provided** in an project repository, to describe something about
300the characteristics, use, capability, etc. of things in that repository.
301A section may also be **referenced** from other sections and in
302other repositories. For example, an API specification provided in a project
303repository might be referenced to in a Platform API Reference Guide.
Rich Bennett7134cba2017-10-10 07:39:06 -0400304The notes in the beginning of each section template provide
Rich Bennettd504dc82018-05-31 08:40:36 -0400305additional detail about what is typically covered and where
306there may be references to the section.
Rich Bennett7134cba2017-10-10 07:39:06 -0400307
Rich Bennettd504dc82018-05-31 08:40:36 -0400308**Collections** Are a set of sections that are typically provided
309for a particular type of project, repository, guide, reference manual, etc.
310For example, a collection for a platform component, an SDK, etc.
Rich Bennett7134cba2017-10-10 07:39:06 -0400311
Rich Bennettd504dc82018-05-31 08:40:36 -0400312You can: browse the template *collections* and *sections* below;
313show source to look at the Restructured Text and Sphinx directives used;
314copy the source either from a browser window or by downloading the
315file in raw form from
Rich Bennett7134cba2017-10-10 07:39:06 -0400316the `gerrit doc repository <https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree;f=docs/templates;/>`_ and
317then add them to your repository docs folder and index.rst.
318
319
320Sections
321++++++++
Rich Bennett5baea462017-09-13 03:19:19 -0400322
323.. toctree::
324 :maxdepth: 1
325 :glob:
326
Rich Bennett7134cba2017-10-10 07:39:06 -0400327 ../../../templates/sections/*
328
329
330Collections
331+++++++++++
332
333.. toctree::
334 :maxdepth: 1
335 :glob:
336
337 ../../../templates/collections/*
338
339
Rich Bennett5baea462017-09-13 03:19:19 -0400340
Blaisonneau David2963ece2017-11-27 10:07:18 +0100341In addition to these simple templates and examples
Rich Bennett5baea462017-09-13 03:19:19 -0400342there are many open source projects (e.g. Open Daylight, Open Stack)
Rich Bennettd504dc82018-05-31 08:40:36 -0400343that are using Sphinx and Readthedocs where you may find examples
344to start with. Working with project teams we will continue to enhance
345templates here and capture frequently asked questions on the developer
346wiki question topic `documentation <https://wiki.onap.org/questions/topics/16384055/documentation>`_.
Rich Bennett5baea462017-09-13 03:19:19 -0400347
Rich Bennettd504dc82018-05-31 08:40:36 -0400348Each 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
357Consider options including filling in a template, identifying existing
358content that can be used as is or easily converted, and use of Sphinx
359directives/extensions to automatically generate restructured text
360from other source you already have.
Rich Bennettac93e0e2017-07-19 01:36:52 -0400361
Rich Bennetta9d6a442017-08-25 02:37:15 -0400362Links and References
Rich Bennett5baea462017-09-13 03:19:19 -0400363--------------------
Rich Bennettac93e0e2017-07-19 01:36:52 -0400364It's pretty common to want to reference another location in the
365ONAP documentation and it's pretty easy to do with
366reStructuredText. 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
370Within a single document, you can reference another section simply by::
371
372 This is a reference to `The title of a section`_
373
374Assuming that somewhere else in the same file there a is a section
375title something like::
376
377 The title of a section
378 ^^^^^^^^^^^^^^^^^^^^^^
379
380It's typically better to use ``:ref:`` syntax and labels to provide
381links as they work across files and are resilient to sections being
382renamed. 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
391Then you can reference the section anywhere by simply doing::
392
393 This is a reference to :ref:`a-label`
394
395or::
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
402Because the labels have to be unique, it usually makes sense to prefix
403the labels with the project name to help share the label space, e.g.,
404``sfc-user-guide`` instead of just ``user-guide``.
405
Rich Bennetta9d6a442017-08-25 02:37:15 -0400406Testing
407=======
Rich Bennettac93e0e2017-07-19 01:36:52 -0400408
Rich Bennetta9d6a442017-08-25 02:37:15 -0400409One RST File
410------------
Rich Bennettac93e0e2017-07-19 01:36:52 -0400411It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards.
412To validate your rst files using doc8, install doc8.
413
414.. code-block:: bash
415
416 sudo pip install doc8
417
418doc8 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 Bennettac93e0e2017-07-19 01:36:52 -0400425
Rich Bennetta9d6a442017-08-25 02:37:15 -0400426One Project
427-----------
Rich Bennettac93e0e2017-07-19 01:36:52 -0400428To test how the documentation renders in HTML, follow these steps:
429
Pawel Wieczorek1a3294f2019-07-10 16:20:22 +0200430Install `virtual environment <https://pypi.org/project/virtualenv>`_ & create one.
Rich Bennettac93e0e2017-07-19 01:36:52 -0400431
432.. code-block:: bash
433
434 sudo pip install virtualenv
Pawel Wieczorek1a3294f2019-07-10 16:20:22 +0200435 virtualenv onap_docs
436
437Activate `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_Robertbf4ab4e2019-07-01 18:12:40 +0200445
446Download a project repository.
447
448.. code-block:: bash
449
Pawel Wieczorek1a3294f2019-07-10 16:20:22 +0200450 git clone http://gerrit.onap.org/r/<project>
Rich Bennettac93e0e2017-07-19 01:36:52 -0400451
452Download the doc repository.
453
454.. code-block:: bash
455
456 git clone http://gerrit.onap.org/r/doc
457
458Change directory to doc & install requirements.
459
460.. code-block:: bash
461
462 cd doc
Pawel Wieczorek1a3294f2019-07-10 16:20:22 +0200463 pip install -r etc/requirements.txt
Rich Bennettac93e0e2017-07-19 01:36:52 -0400464
Rene_Robertbf4ab4e2019-07-01 18:12:40 +0200465Copy the conf.py file to your project folder where RST files have been kept:
Rich Bennettac93e0e2017-07-19 01:36:52 -0400466
467.. code-block:: bash
468
Rene_Robertbf4ab4e2019-07-01 18:12:40 +0200469 cp docs/conf.py <path-to-project-folder>/<folder where are rst files>
Rich Bennettac93e0e2017-07-19 01:36:52 -0400470
Rene_Robertbf4ab4e2019-07-01 18:12:40 +0200471Copy the static files to the project folder where RST files have been kept:
Rich Bennettac93e0e2017-07-19 01:36:52 -0400472
473.. code-block:: bash
474
Rene_Robertbf4ab4e2019-07-01 18:12:40 +0200475 cp -r docs/_static/ <path-to-project-folder>/<folder where are rst files>
Rich Bennettac93e0e2017-07-19 01:36:52 -0400476
477Build the documentation from within your project folder:
478
479.. code-block:: bash
480
Rene_Robertbf4ab4e2019-07-01 18:12:40 +0200481 sphinx-build -b html <path-to-project-folder>/<folder where are rst files> <path-to-output-folder>
Rich Bennettac93e0e2017-07-19 01:36:52 -0400482
483Your documentation shall be built as HTML inside the
484specified output folder directory.
485
Rene_Robertbf4ab4e2019-07-01 18:12:40 +0200486You can use your Web Browser to open
487and check resulting html pages in the output folder.
488
Pawel Wieczorek1a3294f2019-07-10 16:20:22 +0200489.. 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 Bennettac93e0e2017-07-19 01:36:52 -0400490
jsseidel80666192017-09-19 13:29:23 -0400491.. _building-all-documentation:
Rich Bennettac93e0e2017-07-19 01:36:52 -0400492
Rich Bennetta9d6a442017-08-25 02:37:15 -0400493All Documentation
494-----------------
Rich Bennettd504dc82018-05-31 08:40:36 -0400495To build the all documentation under doc/, follow these steps:
Rich Bennettac93e0e2017-07-19 01:36:52 -0400496
Pawel Wieczorek6e823832019-07-10 16:31:27 +0200497Install `tox <https://pypi.org/project/tox>`_.
Rich Bennettac93e0e2017-07-19 01:36:52 -0400498
499.. code-block:: bash
500
Pawel Wieczorek6e823832019-07-10 16:31:27 +0200501 sudo pip install tox
Rich Bennetta9d6a442017-08-25 02:37:15 -0400502
503Download the DOC repository.
504
505.. code-block:: bash
506
507 git clone http://gerrit.onap.org/r/doc
508
Rich Bennett9c3af502018-04-26 09:30:57 -0400509Build documentation using tox local environment & then open using any browser.
Rich Bennetta9d6a442017-08-25 02:37:15 -0400510
511.. code-block:: bash
512
513 cd doc
Cédric Ollivier268209c2017-11-10 11:31:53 +0100514 tox -elocal
Rich Bennetta9d6a442017-08-25 02:37:15 -0400515 firefox docs/_build/html/index.html
516
Cédric Ollivier268209c2017-11-10 11:31:53 +0100517.. note:: Make sure to run `tox -elocal` and not just `tox`.
Rich Bennett50d0d882019-03-08 17:03:58 -0500518 This updates all submodule repositories that are integrated
519 by the doc project.
Rich Bennett9c3af502018-04-26 09:30:57 -0400520
Rich Bennettd504dc82018-05-31 08:40:36 -0400521There are additional tox environment options for checking External
Rene_Robertbf4ab4e2019-07-01 18:12:40 +0200522URLs and Spelling. Use the tox environment options below and then
Rich Bennett50d0d882019-03-08 17:03:58 -0500523look at the output with the Linux `more` or similar command
524scan for output that applies to the files you are validating.
Rich Bennett9c3af502018-04-26 09:30:57 -0400525
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