1 .. _documentation-guide:
7 This guide provides details on how to contribute to the OpenDaylight
8 documentation. OpenDaylight currently uses a mix of AsciiDoc_ and
9 reStructuredText_ for documentation, although the `Documentation
10 Group`_ is generally trying to move toward using reStructuredText_ and
11 Sphinx_ to build it as it is widely-used to provide both HTML and pdf
12 documentation that can be easily versioned alongside the code. It also
13 offers similar syntax to Markdown which is familiar to large numbers of
16 .. contents:: Contents
23 This section serves two purposes:
25 #. A guide for those writing documentation to follow.
26 #. A guide for those reviewing documentation.
28 That being said, assuming that the content is usable, the bias should
29 be toward merging it rather than blocking on relatively minor edits.
31 Formatting Preferences
32 ^^^^^^^^^^^^^^^^^^^^^^
34 In general, the documentation team has focused on trying to make sure
35 that the instructions are comprehensible, but not being overly pedantic
36 about these things. Along those lines, while we would prefer the
37 following, generally they aren't a reason to -1 in and of themselves:
39 * No trailing whitespace
40 * Line wrapping at something reasonable, i.e., 72–100 characters
45 * Functionality: something useful a project provides abstractly
46 * Feature: a Karaf feature that somebody could install
47 * Project: a project within OpenDaylight, projects ship features to
49 * OpenDaylight: this refers to the software we release, use this in
50 place of OpenDaylight controller, the OpenDaylight controller, not
53 * Since there is a controller project within OpenDaylight, using
56 Common writing style mistakes
57 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59 * In per-project user documentation, you should never say *git clone*,
60 but should assume people have downloaded and installed the controller
61 per the getting started guide and start with ``feautre:install
63 * Avoid statements which are true about part of OpenDaylight, but not
66 * For example: "OpenDaylight is a NETCONF controller." It is, but
67 that is not all it is.
69 * In general, developer documentation should target external developers
70 to your project so should talk about what APIs you have and how they
71 could use them. It *should not* document how to contribute to your
77 * Avoid contractions: use cannot instead of can't, it is instead of
80 Things to get right with spacing and capitalization
81 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
83 *Note that all of these apply when using them in text. If they are used
84 as part of URL, class name, or something similar, use the actual
85 capitalization and spacing.*
90 * datastore: not data store, Data Store, or DataStore (unless it's a
92 * IPsec, not IPSEC or ipsec
93 * IPv4 or IPv6: not Ipv4, Ipv6, ipv4, ipv6, IPV4, or IPV6
95 * Linux: not LINUX or linux
96 * NETCONF: not Netconf or netconf
97 * Neutron: not neutron
98 * OSGi: not osgi or OSGI
99 * Open vSwitch: not OpenvSwitch, OpenVSwitch, or Open V Switch, etc.
100 * OpenDaylight: not Opendaylight, Open Daylight, or OpenDayLight, etc.
102 * also avoid abbreviations like ODL and ODC
104 * OpenFlow: not Openflow, Open Flow, openflow, etc.
105 * OpenStack: not Open Stack or Openstack
106 * QoS: not Qos, QOS, or qos
107 * RESTCONF: not Restconf or restconf
111 * YANG: not Yang or yang
113 reStructuredText-based Documentation
114 ====================================
116 When using reStructuredText, we try to follow the python documentation
117 style guide. See: https://docs.python.org/devguide/documenting.html
119 The best reference for reStrucutedText syntax seems to be the Sphinx
120 Primer on reStructuredText_.
122 To build and review the reStructuredText documentation locally you must
123 have installed locally:
128 Which both should be available in most distribution's package managers.
130 Then simply run tox and open the html produced via your favorite web
135 git clone https://git.opendaylight.org/gerrit/docs
137 git submodule update --init
139 firefox docs/_build/html/index.html
141 .. note:: Make sure to run `tox -edocs` and not just `tox`. See `Make
142 sure you run tox -edocs`_
147 The directory structure for the reStructuredText documentation is
148 rooted in the ``docs`` directory inside the ``docs`` ``git``
151 Below that there are guides hosted directly in the ``docs`` ``git``
152 repository and there are guides hosted in remote ``git`` repositories.
153 Usually those are for project-specific information.
155 For example here is the directory layout on June, 28th 2016::
161 ├── documentation.rst
162 ├── getting-started-guide
164 │ ├── concepts_and_tools.rst
165 │ ├── experimental_features.rst
167 │ ├── installing_opendaylight.rst
168 │ ├── introduction.rst
169 │ ├── karaf_features.rst
170 │ ├── other_features.rst
172 │ └── who_should_use.rst
175 ├── opendaylight-with-openstack
178 │ ├── openstack-with-gbp.rst
179 │ ├── openstack-with-ovsdb.rst
180 │ └── openstack-with-vtn.rst
185 The ``getting-started-guide`` and ``opendaylight-with-openstack``
186 directories correspond to two guides hosted in the ``docs`` repository,
187 while the ``submodules/releng/builder`` directory houses documentation
188 for the `RelEng/Builder`_ project.
190 Inside each guide there is usually an ``index.rst`` file which then
191 includes other files using a ``toctree`` directive. For example::
196 getting-started-guide/index
197 opendaylight-with-openstack/index
198 submodules/releng/builder/docs/index
200 This creates a table of contents on that page where each heading of the
201 table of contents is the root of the files that are included.
203 .. note:: When including rst files using ``toctree`` omit the .rst at
204 the end of the file name.
206 Documentation Layout and Style
207 ------------------------------
209 As mentioned previously we try to follow the python documentation style
210 guide which defines a few types of sections::
212 # with overline, for parts
213 * with overline, for chapters
216 ^, for subsubsections
219 We try to follow the following structure based on that recommendation::
221 docs/index.rst -> entry point
222 docs/____-guide/index.rst -> part
223 docs/____-guide/<chapter>.rst -> chapter
225 In the ____-guide/index.rst we use the # with overline at the very top
226 of the file to determine that it is a part and then within each chapter
227 file we start the document with a section using * with overline to
228 denote that it's the chapter heading and then everything in the rest of
229 the chapter should use::
233 ^, for subsubsections
240 Make sure you've cloned submodules
241 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
243 If you see an error like this::
245 ./build-integration-robot-libdoc.sh: line 6: cd: submodules/integration/test/csit/libraries: No such file or directory
246 Resource file '*.robot' does not exist.
248 It means that you haven't pulled down the git submodule for the
249 integration/test project. The fastest way to do that is::
251 git submodule update --init
253 In some cases, you might wind up with submodules which are somehow
254 out-of-sync and in that case, the easiest way to fix it is delete the
255 submodules directory and then re-clone the submodules::
257 rm -rf docs/submodules/
258 git submodule update --init
260 .. warning:: This will delete any local changes or information you made
261 in the submodules. This should only be the case if you
262 manually edited files in that directory.
264 Make sure you run tox -edocs
265 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
267 If you see an error like::
269 ERROR: docs: could not install deps [-rrequirements.txt]; v = InvocationError('/Users/ckd/git-reps/docs/.tox/docs/bin/pip install -rrequirements.txt (see /Users/ckd/git-reps/docs/.tox/docs/log/docs-1.log)', 1)
270 ERROR: docs-linkcheck: could not install deps [-rrequirements.txt]; v = InvocationError('/Users/ckd/git-reps/docs/.tox/docs-linkcheck/bin/pip install -rrequirements.txt (see /Users/ckd/git-reps/docs/.tox/docs-linkcheck/log/docs-linkcheck-1.log)', 1)
272 It usually means you ran `tox` and not `tox -edocs`, which will result
273 in running jobs inside submodules which aren't supported by the
274 environment defined by the `requirements.txt` file in the documentation
275 tox setup. Just run tox -edocs and it should be fine.
277 Clear your tox directory and try again
278 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
280 Sometimes, tox will not detect when your ``requirements.txt`` file has
281 changed and so will try to run things without the correct dependencies.
282 This usually manifests as ``No module named X`` errors or
283 an ``ExtensionError`` and can be fixed by deleting the ``.tox``
284 directory and building again::
289 AsciiDoc-based Documentation
290 ============================
292 Information on the AsciiDoc tools and build system can be found here:
293 https://wiki.opendaylight.org/view/Documentation/Tools
298 The AsciiDoc documentation is all located in the ``manuals`` directory
299 of the ``docs`` ``git`` repository. An example of the directory
300 structure on June 28th, 2016 can be seen here::
305 │ └── app_support.xml
312 ├── getting-started-guide
337 Each of the top-level directories under ``manuals`` is a whole guide by
338 itself and it contains a ``pom.xml`` file saying how to build it, a
339 ``src/main/asciidoc`` directory with AsciiDoc source files and a
340 ``src/main/resources`` directory containing images.
345 See `AsciiDoc Tips`_ on the wiki for more information.
347 Common AsciiDoc mistakes
348 ^^^^^^^^^^^^^^^^^^^^^^^^
350 See also `AsciiDoc Tips`_.
352 * Lists that get formatted incorrectly because of no blank line above
354 * Numbered lists that are formatted incorrectly and every bullet winds
357 Migration from AsciiDoc to ReStructuredText
358 ===========================================
363 In theory, Pandoc_ can convert from DocBook to reStructuredText and we
364 produce DocBook as part of our build chain from AsciiDoctor. In
365 practice, for modest-sized migrations doing things by hand works fairly
371 Converting from AsciiDoc to reStructuredText is usually pretty
372 straightforward and involves looking up the basic syntax for what you
373 want to do by looking it up in the reStructuredText_ guide.
375 The differences are usually minor and fast to change.
377 Also, because of how fast Sphinx builds, and how fast it is to refresh
378 the HTML documentation rapid iteration is very easy.
380 Bold/Italics/Verbatim Formatting
381 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
383 This is mostly minor syntax issues. In AsciiDoc you do inline
384 formatting something like this::
386 *bold* _italic_ +verbatim+ `verbatim`
388 In reStructuredText, things are slightly different::
390 **bold** *italic* ``verbatim``
395 Image formats change from something like::
397 .OpenStack Architecture
398 image::vtn/OpenStackDeveloperGuide.png["OpenStack Architecture",width=500]
402 .. image:: images/dlux-default.png
404 A helpful regular expression for automating the replacements is
407 search: ^( *)\.(.+)\n +image::(.+)\[(.+),width=(\d+)\]
408 replace: $1.. figure:: images/dlux/$3\n$1 :width: $5\n\n$1 $2
414 .. _AsciiDoc: http://www.methods.co.nz/asciidoc/
415 .. _Sphinx: http://www.sphinx-doc.org/en/stable/
416 .. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html
417 .. _Documentation Group: https://wiki.opendaylight.org/view/Documentation/
418 .. _RelEng/Builder: https://wiki.opendaylight.org/view/RelEng/Builder
419 .. _Pandoc: http://pandoc.org/
420 .. _AsciiDoc Tips: https://wiki.opendaylight.org/view/Documentation/Tools/AsciiDoc_Tips