1 .. _documentation-guide:
7 This guide provides details on how to contribute to the OpenDaylight
8 documentation. OpenDaylight currently uses reStructuredText_ for
9 documentation and Sphinx_ to build it as it is widely-used to provide
10 both HTML and pdf documentation that can be easily versioned alongside
11 the code. It also offers similar syntax to Markdown which is familiar
12 to large numbers of people.
14 .. contents:: Contents
21 This section serves two purposes:
23 #. A guide for those writing documentation to follow.
24 #. A guide for those reviewing documentation.
26 That being said, assuming that the content is usable, the bias should
27 be toward merging it rather than blocking on relatively minor edits.
29 Formatting Preferences
30 ----------------------
32 In general, the documentation team has focused on trying to make sure
33 that the instructions are comprehensible, but not being overly pedantic
34 about these things. Along those lines, while we would prefer the
35 following, generally they aren't a reason to -1 in and of themselves:
37 * No trailing whitespace
38 * Line wrapping at something reasonable, i.e., 72–100 characters
43 * Functionality: something useful a project provides abstractly
44 * Feature: a Karaf feature that somebody could install
45 * Project: a project within OpenDaylight, projects ship features to
47 * OpenDaylight: this refers to the software we release, use this in
48 place of OpenDaylight controller, the OpenDaylight controller, not
51 * Since there is a controller project within OpenDaylight, using
54 Common writing style mistakes
55 -----------------------------
57 * In per-project user documentation, you should never say *git clone*,
58 but should assume people have downloaded and installed the controller
59 per the getting started guide and start with ``feautre:install
61 * Avoid statements which are true about part of OpenDaylight, but not
64 * For example: "OpenDaylight is a NETCONF controller." It is, but
65 that is not all it is.
67 * In general, developer documentation should target external developers
68 to your project so should talk about what APIs you have and how they
69 could use them. It *should not* document how to contribute to your
75 * Avoid contractions: use cannot instead of can't, it is instead of
78 Things to get right with spacing and capitalization
79 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
81 *Note that all of these apply when using them in text. If they are used
82 as part of URL, class name, or something similar, use the actual
83 capitalization and spacing.*
88 * datastore: not data store, Data Store, or DataStore (unless it's a
90 * IPsec, not IPSEC or ipsec
91 * IPv4 or IPv6: not Ipv4, Ipv6, ipv4, ipv6, IPV4, or IPV6
93 * Linux: not LINUX or linux
94 * NETCONF: not Netconf or netconf
95 * Neutron: not neutron
96 * OSGi: not osgi or OSGI
97 * Open vSwitch: not OpenvSwitch, OpenVSwitch, or Open V Switch, etc.
98 * OpenDaylight: not Opendaylight, Open Daylight, or OpenDayLight, etc.
100 * also avoid abbreviations like ODL and ODC
102 * OpenFlow: not Openflow, Open Flow, openflow, etc.
103 * OpenStack: not Open Stack or Openstack
104 * QoS: not Qos, QOS, or qos
105 * RESTCONF: not Restconf or restconf
109 * 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.
209 If you want to import a project underneath the documentation project so
210 that the docs can be kept in the separate repo, you can do it using the
211 ``git submodule add`` command as follows::
213 git submodule add -b master ../integration/packaging docs/submodules/integration/packaging
216 .. note:: Most projects will not want to use ``-b master``, but instead
217 use the branch ``.``, which will make track whatever branch
218 of the documentation project you happen to be on.
220 Unfortunately, ``-b .`` doesn't work, so you have to manually
221 edit the ``.gitmodules`` file to add ``branch = .`` and then
222 commit it. Something like::
224 <edit the .gitmodules file>
228 When you're done you should have a git commit something like::
231 commit 7943ce2cb41cd9d36ce93ee9003510ce3edd7fa9
232 Author: Daniel Farrell <dfarrell@redhat.com>
233 Date: Fri Dec 23 14:45:44 2016 -0500
235 Add Int/Pack to git submodules for RTD generation
237 Change-Id: I64cd36ca044b8303cb7fc465b2d91470819a9fe6
238 Signed-off-by: Daniel Farrell <dfarrell@redhat.com>
240 diff --git a/.gitmodules b/.gitmodules
241 index 91201bf6..b56e11c8 100644
245 path = docs/submodules/ovsdb
248 +[submodule "docs/submodules/integration/packaging"]
249 + path = docs/submodules/integration/packaging
250 + url = ../integration/packaging
252 diff --git a/docs/submodules/integration/packaging b/docs/submodules/integration/packaging
254 index 00000000..fd5a8185
256 +++ b/docs/submodules/integration/packaging
258 +Subproject commit fd5a81853e71d45945471d0f91bbdac1a1444386
260 As usual, you can push it to Gerrit with ``git review``.
262 .. important:: It's critical that the Gerrit patch be merged before the
263 git commit hash of the submodule changes. Otherwise,
264 Gerrit won't be able to automatically keep it up-to-date
267 Documentation Layout and Style
268 ------------------------------
270 As mentioned previously we try to follow the python documentation style
271 guide which defines a few types of sections::
273 # with overline, for parts
274 * with overline, for chapters
277 ^, for subsubsections
280 We try to follow the following structure based on that recommendation::
282 docs/index.rst -> entry point
283 docs/____-guide/index.rst -> part
284 docs/____-guide/<chapter>.rst -> chapter
286 In the ____-guide/index.rst we use the # with overline at the very top
287 of the file to determine that it is a part and then within each chapter
288 file we start the document with a section using * with overline to
289 denote that it's the chapter heading and then everything in the rest of
290 the chapter should use::
294 ^, for subsubsections
300 It's pretty common to want to reference another location in the
301 OpenDaylight documentation and it's pretty easy to do with
302 reStructuredText. This is a quick primer, more information is in the
303 `Sphinx section on Cross-referencing arbitrary locations
304 <http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.
306 Within a single document, you can reference another section simply by::
308 This is a reference to `The title of a section`_
310 Assuming that somewhere else in the same file there a is a section
311 title something like::
313 The title of a section
314 ^^^^^^^^^^^^^^^^^^^^^^
316 It's typically better to use ``:ref:`` syntax and labels to provide
317 links as they work across files and are resilient to sections being
318 renamed. First, you need to create a label something like::
322 The title of a section
323 ^^^^^^^^^^^^^^^^^^^^^^
325 .. note:: The underscore (_) before the label is required.
327 Then you can reference the section anywhere by simply doing::
329 This is a reference to :ref:`a-label`
333 This is a reference to :ref:`a section I really liked <a-label>`
335 .. note:: When using ``:ref:``-style links, you don't need a trailing
338 Because the labels have to be unique, it usually makes sense to prefix
339 the labels with the project name to help share the label space, e.g.,
340 ``sfc-user-guide`` instead of just ``user-guide``.
343 .. _docs-rst-troubleshooting:
348 Nested formatting doesn't work
349 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
351 As stated in the reStructuredText_ guide, inline markup for bold,
352 italic, and fixed-width can't be nested. Further, it can't be mixed
353 with hyperlinks, so you can't have bold text link somewhere.
355 This is tracked in a `Docutils FAQ question
356 <http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible>`_,
357 but there is no clear current plan to fix this.
359 Make sure you've cloned submodules
360 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
362 If you see an error like this::
364 ./build-integration-robot-libdoc.sh: line 6: cd: submodules/integration/test/csit/libraries: No such file or directory
365 Resource file '*.robot' does not exist.
367 It means that you haven't pulled down the git submodule for the
368 integration/test project. The fastest way to do that is::
370 git submodule update --init
372 In some cases, you might wind up with submodules which are somehow
373 out-of-sync and in that case, the easiest way to fix it is delete the
374 submodules directory and then re-clone the submodules::
376 rm -rf docs/submodules/
377 git submodule update --init
379 .. warning:: This will delete any local changes or information you made
380 in the submodules. This should only be the case if you
381 manually edited files in that directory.
383 Make sure you run tox -edocs
384 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
386 If you see an error like::
388 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)
389 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)
391 It usually means you ran `tox` and not `tox -edocs`, which will result
392 in running jobs inside submodules which aren't supported by the
393 environment defined by the `requirements.txt` file in the documentation
394 tox setup. Just run tox -edocs and it should be fine.
396 Clear your tox directory and try again
397 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
399 Sometimes, tox will not detect when your ``requirements.txt`` file has
400 changed and so will try to run things without the correct dependencies.
401 This usually manifests as ``No module named X`` errors or
402 an ``ExtensionError`` and can be fixed by deleting the ``.tox``
403 directory and building again::
408 Builds on Read the Docs
409 ^^^^^^^^^^^^^^^^^^^^^^^
411 It appears as though the Read the Docs builds don't automatically clear
412 the file structure between builds and clones. The result is that you
413 may have to clean up the state of old runs of the build script.
415 As an example, this patch:
416 https://git.opendaylight.org/gerrit/41679
418 Finally fixed the fact that our builds for failing because they were
419 taking too long by removing directories of generated javadoc that were
420 present from previous runs.
422 Project Documentation Requirements
423 ==================================
425 Submitting Documentation Outlines (M3)
426 --------------------------------------
428 #. Determine the features your project will have and which ones will be
431 * In general, a feature is user-facing if it creates functionality that a
432 user would direction interact with.
433 * For example, ``odl-openflowplugin-flow-services-ui`` is likely
434 user-facing since it installs user-facing OpenFlow features, while
435 ``odl-openflowplugin-flow-services`` is not because it provides only
436 developer-facing features.
438 #. Determine pieces of documentation you need provide based on the features
439 your project will have and which ones will be user-facing.
441 * The kinds of required documentation can be found below in the
442 :ref:`requirements-for-projects` section.
443 * Note that you might need to create multiple different documents for the
444 same kind of documentation. For example, the controller project will
445 likely want to have a developer section for the config subsystem as well
448 #. Clone the docs repo: ``git clone https://git.opendaylight.org/gerrit/docs``
449 #. For each piece of documentation find the corresponding template in the docs repo.
451 * For user documentation: ``docs.git/docs/templates/template-user-guide.rst``
452 * For developer documentation: ``ddocs/templates/template-developer-guide.rst``
453 * For installation documentation (if any): ``docs/templates/template-install-guide.rst``
455 .. note:: You can find the rendered templates here:
460 templates/template-user-guide
461 templates/template-developer-guide
462 templates/template-install-guide.rst
465 #. Copy the template into the appropriate directory for your project.
467 * For user documentation: ``docs.git/docs/user-guide/${feature-name}-user-guide.rst``
468 * For developer documentation: ``docs.git/docs/developer-guide/${feature-name}-developer-guide.rst``
469 * For installation documentation (if any): ``docs.git/docs/getting-started-guide/project-specific-guides/${project-name}.rst``
471 .. note:: These naming conventions aren't set in stone, but do help. If you
472 think there's a better name, use it and we'll give feedback on the
475 #. Edit the template to fill in the outline of what you will provide using the
476 suggestions in the template. If you feel like a section isn't needed, feel
479 #. Link the template into the appropriate core rst file
481 * For user documentation: ``docs.git/docs/user-guide/index.rst``
482 * For developer documentation: ``docs.git/docs/developer-guide/index.rst``
483 * For installation documentation (if any): ``docs.git/docs/getting-started-guide/project-specific-guides/index.rst``
484 * In each file, it should be pretty clear what line you need to add. In
485 general if you have an rst file ``project-name.rst``, you include it by
486 adding a new line ``project-name`` without the ``.rst`` at the end.
488 #. Make sure the documentation project still builds.
490 * Run ``tox -edocs`` from the root of the cloned docs repo.
492 * After that, you should be able to find the HTML version of the
493 docs at ``docs.git/docs/_build/html/index.html``.
494 * See :ref:`docs-rst` for more details about building the docs.
496 * The :ref:`reStructuredText Troubleshooting <docs-rst-troubleshooting>`
497 section provides common errors and solutions.
498 * If you still have problems e-mail the documentation group at
499 documentation@lists.opendaylight.org
501 #. Commit and submit the patch
507 git add --all && git commit -sm "Documentation outline for ${project-shortname}"
515 See the `Git-review Workflow <https://wiki.opendaylight.org/view/Git-review_Workflow>`_
516 page if you don't have git-review installed.
518 #. Wait for the patch to be merged or to get feedback
520 * If you get feedback, make the requested changes and resubmit the patch.
521 * When you resubmit the patch, it's helpful if you also post a +0 reply to
522 the gerrit saying what patch set you just submitted and what you fixed in
524 * The documentation team will also be creating (or asking projects to
525 create) small groups of 2-4 projects that will peer review each other's
526 documentation. Patches which have seen a few cycles of peer review will be
527 prioritized for review and merge by the documentation team.
529 Expected Output From Documentation Project
530 ------------------------------------------
532 The expected output is (at least) 3 PDFs and equivalent web-based documentation:
534 * User/Operator Guide
538 These guides will consist of "front matter" produced by the documentation group
539 and the per-project/per-feature documentation provided by the projects. Note
540 that this is intended to be who is responsible for the documentation and should
541 not be interpreted as preventing people not normally in the documentation group
542 from helping with "front matter" nor preventing people from the documentation
543 group from helping with per-project/per-feature documentation.
545 Boron Project Documentation Requirements
546 ----------------------------------------
550 Kinds of Documentation
551 ^^^^^^^^^^^^^^^^^^^^^^
553 These are the expected kinds of documentation and target audiences for each kind.
555 * **User/Operator:** for people looking to use the feature w/o writing code
557 * Should include an overview of the project/feature
558 * Should include description of availbe configuration options and what they do
560 * **Developer:** for people looking to use the feature in code w/o modifying it
562 * Should include API documentation, e.g., enunciate for REST, Javadoc for
563 Java, ??? for RESTCONF/models
565 * **Contributor:** for people looking to extend or modify the feature's source
570 should be documented on the wiki not in reStructuredText
572 * **Installation:** for people looking for instructions to install the feature
573 after they have downloaded the ODL release
577 audience is the same as User/Operator docs
579 * For most projects, this will be just a list of top-level features and
582 * As an example, l2switch-switch as the top-level feature with the -rest
584 * We'd also like them to note if the options should be checkboxes (i.e.,
585 they can each be turned on/off independently) or a drop down (i.e., at
586 most one can be selected)
587 * What other top-level features in the release are incompatible with each
589 * This will likely be presented as a table in the documentation and the
590 data will likely also be consumed by automated installers/configurators/downloaders
592 * For some projects, there is extra installation instructions (for external
593 components) and/or configuration
595 * In that case, there will be a (sub)section in the documentation
596 describing this process.
598 * **HowTo/Tutorial:** walk throughs and examples that are not general-purpose
601 * Generally, these should be done as a (sub)section of either user/operator
602 or developer documentation.
603 * If they are especially long or complex, they may belong on their own
607 * Release notes are required as part of each project's release review. They
608 must also be translated into reStructuredText for inclusion in the formal
611 .. _requirements-for-projects:
613 Requirements for projects
614 ^^^^^^^^^^^^^^^^^^^^^^^^^
616 Projects MUST do the following
618 * Provide reStructuredText documentation including
620 * Developer documentation for every feature
622 * Most projects will want to logically nest the documentation for
623 individual features under a single project-wide chapter or section
624 * This can be provided as a single .rst file or multiple .rst files if
625 the features fall into different groups
626 * This should start with ~300 word overview of the project and include
627 references to any automatically-generated API documentation as well as
628 more general developer information (see
629 :ref:`kinds-of-docs`).
631 * User/Operator documentation for every every user-facing feature (if any)
633 * ''Note: This should be per-feature, not per-project. User's shouldn't have to know which project a feature came from.''
634 * Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences
635 * This can be provided as a single .rst file or multiple .rst files if the features fall into different groups
637 * Installation documentation
639 * Most projects will simply provide a list of user-facing features and
640 options. See :ref:`kinds-of-docs` above.
642 * Release Notes (both on the wiki and reStructuredText) as part of the release review.
644 * This documentation will be contributed to the docs repo (or possibly imported from the project's own repo with tooling that is under development)
646 * Projects MAY be ENCOURGAGED to instead provide this from their own repository if the tooling is developed
647 * Projects choosing to meet the requirement this way MUST provide a patch to docs repo to import the project's documentation
649 * Projects MUST cooperate with the documentation group on edits and enhancements to documentation
651 * Note that the documentation team will also be creating (or asking projects to create) small groups of 2-4 projects that will peer review each other's documentation. Patches which have seen a few cycles of peer review will be prioritized for review and merge by the documentation team.
653 Timeline for Deliverables from Projects
654 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
656 * **M3:** Documentation Started
658 * Identified the kinds of documentation that will be provided and for what
661 * Release Notes are not required until release reviews at **RC2**
663 * Created the appropriate .rst files in the docs repository (or their own
664 repository if the tooling is available)
665 * Have an outline for the expected documentation in those .rst files
666 including the relevant (sub)sections and a sentence or two explaining what
669 * Obviusly, providing actual documentation in the (sub)sections is
670 encouraged and meets this requirement
672 * Milestone readout should include
674 #. the list of kinds of documentation
675 #. the list of corresponding .rst files and their location, e.g., repo and
677 #. the list of commits creating those .rst files
678 #. the current word counts of those .rst files
680 * **M4:** Documentation Continues
682 * The readout at M4 should include the word counts of all .rst files with
684 * The goal is to have draft documentation complete so that the documentation
685 group can comment on it.
687 * **M5:** Documentation Complete
689 * All (sub)sections in all .rst files have complete, readable, usable content.
690 * Ideally, there should have been some interaction with the documentation
691 group about any suggested edits and enhancements
693 * **RC2:** Release notes
695 * Projects must provide release notes as .rst pushed to integration (or
696 locally in the project's repository if the tooling is developed)
699 .. _Sphinx: http://www.sphinx-doc.org/en/stable/
700 .. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html
701 .. _Documentation Group: https://wiki.opendaylight.org/view/Documentation/
702 .. _RelEng/Builder: https://wiki.opendaylight.org/view/RelEng/Builder
703 .. _Pandoc: http://pandoc.org/