1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
6 Some initial set up is required to connect a project with
7 the master document structure and enable automated publishing of
8 changes as summarized in the following diagram and description below
16 RD [label = "Read The Docs", color =lightgreen ];
17 DA [label = "Doc Project\nAuthor/Committer", color=lightblue];
18 DR [label = "Doc Gerrit Repo" , color=pink];
19 PR [label = "Other Project\nGerrit Repo", color=pink ];
20 PA [label = "Other Project\nAuthor/Committer", color=lightblue];
22 === One time setup doc project only ===
23 RD -> DA [label = "Acquire Account" ];
24 DA -> DR [label = "Create initial\n doc repository content"];
25 DA <<-- DR [label = "Merge" ];
26 RD <-- DA [label = "Connect gerrit.onap.org" ];
27 === For each new project repository containing document source ===
28 DA -> PR [label = "Create in new project repo\ntop level directory and index.rst" ];
29 PR <-- PA [label = "Review/Approve" ];
30 DA <-- PR [label = "Merge" ];
31 DA -> DR [label = "Add new project repo as\ngit submodule" ];
32 DA <-- DR [label = "Merge" ];
39 These steps are performed only once for the doc project and include:
41 (1) creating in the doc repository an initial:
42 - sphinx master document index
43 - a directory structure aligned with the document structure
44 - tests performed in jenkins verify jobs
45 - sphinx configuration
47 (2) establishing an account at readthedocs connected with the doc
48 doc project repo in gerrit.onap.org.
51 Setup new project repositories(s)
52 ---------------------------------
53 These steps are performed for each new project repo (referred to in the
54 next two code blocks as $reponame):
56 (1) clone, modify, and commit to the other project an initial: docs top
57 level directory; index.rst; any other intial content.
62 git clone ssh://<your_id>@gerrit.onap.org:29418/$reponame
65 echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License.
67 TODO Add files to toctree and delete this header
68 ------------------------------------------------
75 git commit -m "Add RST docs directory and index" -s
77 # modify the commit message to comply with ONAP best practices
80 When the above commit is reviewed and merged complete step 2 before any
81 new changes are merged into $reponame.
83 (2) clone, modify, and commit to the doc project: a directory under doc/docs/submodules with the same path/name as the other project and initialized as a git submodule.
87 git clone ssh://<your_id>@gerrit.onap.org:29418/doc
88 # For top level repositories use the following
89 mkdir doc/docs/submodules/$reponame
90 # For lower level repositories you may need to make a directory for each node in path
92 echo " $reponame <../submodules/$reponame/docs/index>" >> docs/release/repolist.rst
94 git submodule git https://gerrit.onap.org/r/$reponame
95 git submodule init $reponame/
96 git submodule update $reponame/
100 git commit -m "Add $reponame as a submodule" -s
102 # modify the commit message to comply with ONAP best practices
107 The diagram below illustrates what is accomplished in the setup steps
108 above from the perspective of a file structure created for a local test,
109 a jenkins verify job, and/or publish release documentation including:
111 - all ONAP gerrit project repositories,
112 - the doc project repository master document index.rst, templates, configuration
113 - the submodules directory where other project repositories and directories/files may be referenced
119 digraph docstructure {
121 node [fontname = "helvetica"];
122 // Align gerrit repos and docs directories
123 {rank=same doc aaf aai reponame repoelipse vnfsdk vvp}
124 {rank=same confpy release templates masterindex submodules otherdocdocumentelipse}
127 //Illustrate Gerrit Repos and provide URL/Link for complete repo list
128 gerrit [label="gerrit.onap.org/r", href="https://gerrit.onap.org/r/#/admin/projects/" ];
133 gerrit -> repoelipse;
134 repoelipse [label=". . . ."];
138 //Show example of local reponame instance of component info
139 reponame -> reponamedocsdir;
140 reponamesm -> reponamedocsdir;
141 reponamedocsdir [label="docs"];
142 reponamedocsdir -> newrepodocsdirindex;
143 newrepodocsdirindex [label="index.rst", shape=box];
145 //Show detail structure of a portion of doc/docs
148 confpy [label="conf.py",shape=box];
150 masterindex [label="Master index.rst", shape=box];
153 docs -> otherdocdocumentelipse;
154 otherdocdocumentelipse [label="...other\ndocuments"];
157 masterindex -> releasedocumentindex [style=dashed, label="sphinx\ntoctree\nreference"];
159 //Show submodule linkage to docs directory
160 submodules -> reponamesm [style=dotted,label="git\nsubmodule\nreference"];
161 reponamesm [label="reponame"];
163 //Example Release document index that references component info provided in other project repo
164 release -> releasedocumentindex;
165 releasedocumentindex [label="index.rst", shape=box];
166 releasedocumentindex -> newrepodocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"];
170 Creating Restructured Text
171 ==========================
173 TODO Add simple example and references here
177 It's pretty common to want to reference another location in the
178 ONAP documentation and it's pretty easy to do with
179 reStructuredText. This is a quick primer, more information is in the
180 `Sphinx section on Cross-referencing arbitrary locations
181 <http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.
183 Within a single document, you can reference another section simply by::
185 This is a reference to `The title of a section`_
187 Assuming that somewhere else in the same file there a is a section
188 title something like::
190 The title of a section
191 ^^^^^^^^^^^^^^^^^^^^^^
193 It's typically better to use ``:ref:`` syntax and labels to provide
194 links as they work across files and are resilient to sections being
195 renamed. First, you need to create a label something like::
199 The title of a section
200 ^^^^^^^^^^^^^^^^^^^^^^
202 .. note:: The underscore (_) before the label is required.
204 Then you can reference the section anywhere by simply doing::
206 This is a reference to :ref:`a-label`
210 This is a reference to :ref:`a section I really liked <a-label>`
212 .. note:: When using ``:ref:``-style links, you don't need a trailing
215 Because the labels have to be unique, it usually makes sense to prefix
216 the labels with the project name to help share the label space, e.g.,
217 ``sfc-user-guide`` instead of just ``user-guide``.
224 It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards.
225 To validate your rst files using doc8, install doc8.
229 sudo pip install doc8
231 doc8 can now be used to check the rst files. Execute as,
235 doc8 --ignore D000,D001 <file>
241 To test how the documentation renders in HTML, follow these steps:
243 Install virtual environment.
247 sudo pip install virtualenv
248 cd /local/repo/path/to/project
250 Download the doc repository.
254 git clone http://gerrit.onap.org/r/doc
256 Change directory to doc & install requirements.
261 sudo pip install -r etc/requirements.txt
263 Move the conf.py file to your project folder where RST files have been kept:
267 mv doc/docs/conf.py <path-to-your-folder>/
269 Move the static files to your project folder:
273 mv docs/_static/ <path-to-your-folder>/
275 Build the documentation from within your project folder:
279 sphinx-build -b html <path-to-your-folder> <path-to-output-folder>
281 Your documentation shall be built as HTML inside the
282 specified output folder directory.
284 .. 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.
289 To build the whole documentation under doc/, follow these steps:
291 Install virtual environment.
295 sudo pip install virtualenv
296 cd /local/repo/path/to/project
298 Download the DOC repository.
302 git clone http://gerrit.onap.org/r/doc
304 Change directory to docs & install requirements.
309 sudo pip install -r etc/requirements.txt
311 Update submodules, build documentation using tox & then open using any browser.
316 git submodule update --init
318 firefox docs/_build/html/index.html
320 .. note:: Make sure to run `tox -edocs` and not just `tox`.