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. These documentation tools are widely used
10 in open source communities to produce both HTML and PDF documentation and can
11 be easily versioned alongside the code. reStructuredText also offers similar
12 syntax to Markdown, which is familiar to many developers.
14 .. contents:: Contents
21 This section serves two purposes:
23 #. A guide for those writing documentation.
24 #. A guide for those reviewing documentation.
26 .. note:: When reviewing content, assuming that the content is usable, the
27 documentation team is biased toward merging the content rather than
28 blocking it due to relatively minor editorial issues.
30 Formatting Preferences
31 ----------------------
33 In general, when reviewing content, the documentation team ensures that it
34 is comprehensible but tries not to be overly pedantic. Along those lines,
35 while it is preferred that the following formatting preferences are followed,
36 they are generally not an exclusive reason to give a "-1" reply to a patch in
39 * No trailing whitespace
40 * Line wrapping at something reasonable, that is, 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 ``feature: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
83 .. note:: The following word choice guidelines apply when using these terms in
84 text. If these terms are used as part of a URL, class name, or
85 any instance where modifying the case would create issues, use the
86 exact capitalization and spacing associated with the URL or class
89 * ACL: not ``Acl`` or ``acl``
91 * ARP: not ``Arp`` or ``arp``
92 * datastore: not data store, Data Store, or DataStore (unless it is a
94 * ``IPsec``: not IPSEC or ``ipsec``
95 * ``IPv4`` or ``IPv6``: not ``Ipv4``, ``Ipv6``, ``ipv4``, ``ipv6``, ``IPV4``, or ``IPV6``
97 * Linux: not LINUX or ``linux``
98 * NETCONF: not Netconf or netconf
99 * Neutron: not neutron
100 * OSGi: not ``osgi`` or OSGI
101 * ``Open vSwitch``: not OpenvSwitch, OpenVSwitch, or Open V Switch.
102 * OpenDaylight: not ``Opendaylight``, ``Open Daylight``, or ``OpenDayLight``.
104 .. note:: Also, avoid OpenDaylight abbreviations such as ODL and OD.
106 * OpenFlow: not ``Openflow``, ``Open Flow``, or ``openflow``.
107 * OpenStack: not ``Open Stack`` or ``Openstack``
108 * QoS: not ``Qos``, ``QOS``, or ``qos``
109 * RESTCONF: not ``Restconf`` or ``restconf``
110 * RPC not ``Rpc`` or ``rpc``
111 * URL not ``Url`` or ``url``
112 * VM: not ``Vm`` or ``vm``
113 * YANG: not Yang or yang
117 reStructuredText-based Documentation
118 ====================================
120 When using reStructuredText, follow the Python documentation
121 style guidelines. See: https://devguide.python.org/documenting/
123 One of the best references for reStructuredText syntax is the Sphinx
124 Primer on reStructuredText_.
126 To build and review the reStructuredText documentation locally, you must
127 have the following packages installed locally:
132 .. note:: Both packages should be available in most distribution package
135 Then simply run ``tox`` and open the HTML produced by using your favorite web
140 git clone https://git.opendaylight.org/gerrit/docs
142 git submodule update --init
144 firefox docs/_build/html/index.html
149 The directory structure for the reStructuredText documentation is
150 rooted in the ``docs`` directory inside the ``docs`` ``git``
153 .. note:: There are guides hosted directly in the ``docs`` ``git``
154 repository and there are guides hosted in remote ``git`` repositories.
155 Documentation hosted in remote ``git`` repositories are generally
156 provided for project-specific information.
158 For example, here is the directory layout on ``June, 28th 2016``::
164 ├── documentation.rst
165 ├── getting-started-guide
167 │ ├── concepts_and_tools.rst
168 │ ├── experimental_features.rst
170 │ ├── installing_opendaylight.rst
171 │ ├── introduction.rst
172 │ ├── karaf_features.rst
173 │ ├── other_features.rst
175 │ └── who_should_use.rst
178 ├── opendaylight-with-openstack
181 │ ├── openstack-with-gbp.rst
182 │ ├── openstack-with-ovsdb.rst
183 │ └── openstack-with-vtn.rst
188 The ``getting-started-guide`` and ``opendaylight-with-openstack``
189 directories correspond to two guides hosted in the ``docs`` repository,
190 while the ``submodules/releng/builder`` directory houses documentation
191 for the `RelEng/Builder`_ project.
193 Each guide includes an ``index.rst`` file, which uses a ``toctree``
194 directive that includes the other files associated with the guide. For example::
199 getting-started-guide/index
200 opendaylight-with-openstack/index
201 submodules/releng/builder/docs/index
203 This example creates a table of contents on that page where each heading of the
204 table of contents is the root of the files that are included.
206 .. note:: When including ``.rst`` files using the ``toctree`` directive, omit
207 the ``.rst`` file extension at the end of the file name.
212 If you want to import a project underneath the documentation project so
213 that the docs can be kept in the separate repository, you can do it by using the
214 ``git submodule add`` command as follows::
216 git submodule add -b master ../integration/packaging docs/submodules/integration/packaging
219 .. note:: Most projects will not want to use ``-b master``, but instead
220 use the branch ``.``, which tracks whatever branch
221 of the documentation project you happen to be on.
223 Unfortunately, ``-b .`` does not work, so you have to manually
224 edit the ``.gitmodules`` file to add ``branch = .`` and then
225 commit it. For example::
227 <edit the .gitmodules file>
231 When you're done you should have a git commit something like::
234 commit 7943ce2cb41cd9d36ce93ee9003510ce3edd7fa9
235 Author: Daniel Farrell <dfarrell@redhat.com>
236 Date: Fri Dec 23 14:45:44 2016 -0500
238 Add Int/Pack to git submodules for RTD generation
240 Change-Id: I64cd36ca044b8303cb7fc465b2d91470819a9fe6
241 Signed-off-by: Daniel Farrell <dfarrell@redhat.com>
243 diff --git a/.gitmodules b/.gitmodules
244 index 91201bf6..b56e11c8 100644
248 path = docs/submodules/ovsdb
251 +[submodule "docs/submodules/integration/packaging"]
252 + path = docs/submodules/integration/packaging
253 + url = ../integration/packaging
255 diff --git a/docs/submodules/integration/packaging b/docs/submodules/integration/packaging
257 index 00000000..fd5a8185
259 +++ b/docs/submodules/integration/packaging
261 +Subproject commit fd5a81853e71d45945471d0f91bbdac1a1444386
263 As usual, you can push it to Gerrit with ``git review``.
265 .. important:: It is critical that the Gerrit patch be merged before the
266 git commit hash of the submodule changes. Otherwise,
267 Gerrit is not able to automatically keep it up-to-date
270 Documentation Layout and Style
271 ------------------------------
273 As mentioned previously, OpenDaylight aims to follow the Python documentation
274 style guidelines, which defines a few types of sections::
276 # with overline, for parts
277 * with overline, for chapters
280 ^, for subsubsections
283 OpenDaylight documentation is organized around the following structure based on
284 that recommendation::
286 docs/index.rst -> entry point
287 docs/____-guide/index.rst -> part
288 docs/____-guide/<chapter>.rst -> chapter
290 In the ``____-guide/index.rst`` we use the ``#`` with overline at the very top
291 of the file to determine that it is a part and then within each chapter
292 file we start the document with a section using ``*`` with overline to
293 denote that it is the chapter heading and then everything in the rest of
294 the chapter should use::
298 ^, for subsubsections
304 This section provides a quick primer for creating references
305 in OpenDaylight documentation. For more information, refer to
306 `Cross-referencing documents
307 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_.
309 Within a single document, you can reference another section simply by::
311 This is a reference to `The title of a section`_
313 Assuming that somewhere else in the same file, there a is a section
314 title something like::
316 The title of a section
317 ^^^^^^^^^^^^^^^^^^^^^^
319 It is typically better to use ``:ref:`` syntax and labels to provide
320 links as they work across files and are resilient to sections being
321 renamed. First, you need to create a label something like::
325 The title of a section
326 ^^^^^^^^^^^^^^^^^^^^^^
328 .. note:: The underscore (_) before the label is required.
330 Then you can reference the section anywhere by simply doing::
332 This is a reference to :ref:`a-label`
336 This is a reference to :ref:`a section I really liked <a-label>`
339 .. note:: When using ``:ref:``-style links, you don't need a trailing
342 Because the labels have to be unique, a best practice is to prefix
343 the labels with the project name to help share the label space; for example,
344 use ``sfc-user-guide`` instead of just ``user-guide``.
346 Referencing JIRA issues
347 ^^^^^^^^^^^^^^^^^^^^^^^
349 In order to reference JIRA, we provide two new directives, ``jira_fixed_issues`` and
350 ``jira_known_issues``. These render a table of issues for a particular project and
351 its version range. These are used like this:
355 .. jira_fixed_issues::
357 :versions: 4.0.0-4.0.3
359 .. jira_known_issues::
361 :versions: 4.0.0-4.0.3
364 .. _docs-rst-troubleshooting:
369 Nested formatting does not work
370 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
372 As stated in the reStructuredText_ guide, inline markup for bold,
373 italic, and fixed-width font cannot be nested. Furthermore, inline markup cannot
374 be mixed with hyperlinks, so you cannot have a link with bold text.
376 This is tracked in a `Docutils FAQ question
377 <https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible>`_,
378 but there is no clear current plan to fix this.
380 Make sure you have cloned submodules
381 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
383 If you see an error like this::
385 ./build-integration-robot-libdoc.sh: line 6: cd: submodules/integration/test/csit/libraries: No such file or directory
386 Resource file '*.robot' does not exist.
388 It means that you have not pulled down the git submodule for the
389 integration/test project. The fastest way to do that is::
391 git submodule update --init
393 In some cases, you might wind up with submodules which are somehow
394 out-of-sync. In that case, the easiest way to fix them is to delete the
395 submodules directory and then re-clone the submodules::
397 rm -rf docs/submodules/
398 git submodule update --init
400 .. warning:: These steps delete any local changes or information you made
401 in the submodules, which would only occur if you
402 manually edited files in that directory.
404 Clear your tox directory and try again
405 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
407 Sometimes, tox will not detect when your ``requirements.txt`` file has
408 changed and so will try to run things without the correct dependencies.
409 This issue usually manifests as ``No module named X`` errors or
410 an ``ExtensionError`` and can be fixed by deleting the ``.tox``
411 directory and building again::
416 Builds on Read the Docs
417 ^^^^^^^^^^^^^^^^^^^^^^^
419 Read the Docs builds do not automatically clear the file structure between
420 builds and clones. The result is that you may have to clean up the state of
421 old runs of the build script.
423 As an example, refer to the following patch:
424 https://git.opendaylight.org/gerrit/c/docs/+/41679/
426 This patch fixed the issue that caused builds to fail because they were
427 taking too long removing directories associated with generated
428 Javadoc files that were present from previous runs.
430 Errors from ``Coala``
431 ^^^^^^^^^^^^^^^^^^^^^
433 As part of running ``tox``, two environments run: ``coala`` which does a variety
434 of reStructuredText_ (and other) linting, and ``docs``, which runs Sphinx_ to
435 build HTML and PDF documentation. You can run them independently by doing
436 ``tox -ecoala`` or ``tox -edocs``.
438 The ``coala`` linter for reStructuredText is not always the most helpful in
439 explaining why it failed. So, here are some common ones. There should also be
440 Jenkins Failure Cause Management rules that will highlight these for you.
442 Git Commit Message Errors
443 """""""""""""""""""""""""
445 ``Coala`` checks that git commit messages adhere to the following rules:
447 * ``Shortlog`` (1st line of commit message) is less than 50 characters
448 * ``Shortlog`` (1st line of commit message) is in the imperative mood. For example,
449 "Add foo unit test" is good, but "Adding foo unit test is bad""
450 * Body (all lines but 1st line of commit message) are less than 72 characters.
451 Some exceptions seem to exist, such as for long URLs.
453 Some examples of those being logged are:
457 | | [NORMAL] GitCommitBear:
458 | | ``Shortlog`` of HEAD commit isn't in imperative mood! Bad words are 'Adding'
462 | | [NORMAL] GitCommitBear:
463 | | Body of HEAD commit contains too long lines. Commit body lines should not exceed 72 characters.
465 Error in "code-block" directive
466 """""""""""""""""""""""""""""""
468 If you see an error like this:
472 | 89| ···..·code-block::·bash
473 | | [MAJOR] RSTcheckBear:
474 | | (ERROR/3) Error in "code-block" directive:
476 It means that the relevant code-block is not valid for the
477 language specified, in this case ``bash``.
479 .. note:: If you do not specify a language, the default language is Python. If
480 you want the code-block to not be an any particular language, instead
481 use the ``::`` directive. For example:
486 that will not be parsed
487 in any particular language
489 Project Documentation Requirements
490 ==================================
492 Submitting Documentation Outlines (M2)
493 --------------------------------------
495 #. Determine the features your project will have and which ones will be
498 * In general, a feature is user-facing if it creates functionality that a
499 user would directly interact with.
500 * For example, ``odl-openflowplugin-flow-services-ui`` is likely
501 user-facing since it installs user-facing OpenFlow features, while
502 ``odl-openflowplugin-flow-services`` is not because it provides only
503 developer-facing features.
505 #. Determine pieces of documentation that you need to provide based on the
506 features your project will have and which ones will be user-facing.
508 * The kinds of required documentation can be found below in the
509 :ref:`requirements-for-projects` section.
511 .. note:: You might need to create multiple documents for the
512 same kind of documentation. For example, the controller project
513 will likely want to have a developer section for the config
514 subsystem as well as for the MD-SAL.
516 #. Clone the docs repository: ``git clone https://git.opendaylight.org/gerrit/docs``
517 #. For each piece of documentation find the corresponding template in the docs
520 * For user documentation: ``docs.git/docs/templates/template-user-guide.rst``
521 * For developer documentation: ``ddocs/templates/template-developer-guide.rst``
522 * For installation documentation (if any): ``docs/templates/template-install-guide.rst``
524 .. note:: You can find the rendered templates here:
529 templates/template-user-guide
530 templates/template-developer-guide
531 templates/template-install-guide.rst
534 #. Copy the template into the appropriate directory for your project.
536 * For user documentation: ``docs.git/docs/user-guide/${feature-name}-user-guide.rst``
537 * For developer documentation: ``docs.git/docs/developer-guide/${feature-name}-developer-guide.rst``
538 * For installation documentation (if any): ``docs.git/docs/getting-started-guide/project-specific-guides/${project-name}.rst``
540 .. note:: These naming conventions are not set in stone, but are used to
541 maintain a consistent document taxonomy. If these conventions
542 are not appropriate or do not make sense for a document
543 in development, use the convention that you think is more
544 appropriate and the documentation team will review it and give
545 feedback on the Gerrit patch.
547 #. Edit the template to fill in the outline of what you will provide using the
548 suggestions in the template. If you feel like a section is not needed, feel
551 #. Link the template into the appropriate core ``.rst`` file.
553 * For user documentation: ``docs.git/docs/user-guide/index.rst``
554 * For developer documentation: ``docs.git/docs/developer-guide/index.rst``
555 * For installation documentation (if any): ``docs.git/docs/getting-started-guide/project-specific-guides/index.rst``
556 * In each file, it should be pretty clear what line you need to add. In
557 general if you have an ``.rst`` file ``project-name.rst``, you include it
558 by adding a new line ``project-name`` without the ``.rst`` at the end.
560 #. Make sure the documentation project still builds.
562 * Run ``tox`` from the root of the cloned docs repository.
564 * After that, you should be able to find the HTML version of the
565 docs at ``docs.git/docs/_build/html/index.html``.
566 * See :ref:`docs-rst` for more details about building the docs.
568 * The :ref:`reStructuredText Troubleshooting <docs-rst-troubleshooting>`
569 section provides common errors and solutions.
570 * If you still have problems e-mail the documentation group at
571 documentation@lists.opendaylight.org
573 #. Commit and submit the patch.
579 git add --all && git commit -sm "Documentation outline for ${project-shortname}"
587 See the `Git-review Workflow <https://wiki-archive.opendaylight.org/view/Git-review_Workflow>`_
588 page if you don't have git-review installed.
590 #. Wait for the patch to be merged or to get feedback
592 * If you get feedback, make the requested changes and resubmit the patch.
593 * When you resubmit the patch, it is helpful if you also post a "+0" reply to
594 the patch in Gerrit, stating what patch set you just submitted and what you
595 fixed in the patch set.
597 Expected Output From Documentation Project
598 ------------------------------------------
600 The expected output is (at least) 3 PDFs and equivalent web-based documentation:
602 * User/Operator Guide
606 These guides will consist of "front matter" produced by the documentation group
607 and the per-project/per-feature documentation provided by the projects.
609 .. note:: This requirement is intended for the person responsible for the
610 documentation and should not be interpreted as preventing people not
611 normally in the documentation group from helping with front matter
612 nor preventing people from the documentation group from helping with
613 per-project/per-feature documentation.
615 Project Documentation Requirements
616 ----------------------------------
623 These are the expected kinds of documentation and target audiences for each
626 * **User/Operator:** for people looking to use the feature without writing code
628 * Should include an overview of the project/feature
629 * Should include description of available configuration options and what they
632 * **Developer:** for people looking to use the feature in code without modifying
635 * Should include API documentation, such as, enunciate for REST, Javadoc for
636 Java, ??? for RESTCONF/models
638 * **Contributor:** for people looking to extend or modify the feature's source
641 .. note:: You can find this information on the wiki.
643 * **Installation:** for people looking for instructions to install the feature
644 after they have downloaded the ODL release
646 .. note:: The audience for this content is the same as User/Operator docs
648 * For most projects, this will be just a list of top-level features and
651 * As an example, l2switch-switch as the top-level feature with the -rest
653 * Features should also note if the options should be check-boxes (that is,
654 they can each be turned on/off independently) or a drop-down (that is, at
655 most one can be selected)
656 * What other top-level features in the release are incompatible with each
658 * This will likely be presented as a table in the documentation and the
659 data will likely also be consumed by an automated installer or configurator
662 * For some projects, there is extra installation instructions (for external
663 components) and/or configuration
665 * In that case, there will be a (sub)section in the documentation
666 describing this process.
668 * **HowTo/Tutorial:** walk-through and examples that are not general-purpose
671 * Generally, these should be done as a (sub)section of either user/operator
672 or developer documentation.
673 * If they are especially long or complex, they may belong on their own
677 * Release notes are required as part of each project's release review. They
678 must also be translated into reStructuredText for inclusion in the formal
681 .. _requirements-for-projects:
683 Requirements for projects
684 ^^^^^^^^^^^^^^^^^^^^^^^^^
686 * Projects must provide reStructuredText documentation including:
688 * Developer documentation for every feature
690 * Most projects will want to logically nest the documentation for
691 individual features under a single project-wide chapter or section
692 * The feature documentation can be provided as a single ``.rst`` file or
693 multiple ``.rst`` files if the features fall into different groups
694 * Feature documentation should start with approximately 300 words overview
695 of the project and include references to any automatically-generated API
696 documentation as well as more general developer information (see
697 :ref:`kinds-of-docs`).
699 * User/Operator documentation for every every user-facing feature (if any)
701 * This documentation should be per-feature, not per-project. Users should
702 not have to know which project a feature came from.
703 * Intimately related features can be documented together. For example,
704 ``l2switch-switch``, ``l2switch-switch-rest``, and ``l2switch-switch-ui``,
705 can be documented as one noting the differences.
706 * This documentation can be provided as a single ``.rst`` file or multiple
707 ``.rst`` files if the features fall into different groups
709 * Installation documentation
711 * Most projects will simply provide a list of user-facing features and
712 options. See :ref:`kinds-of-docs` above.
714 * Release Notes (both on the wiki and reStructuredText) as part of the release
717 * Documentation must be imported from the project own repository or contributed
718 to the docs repository for generic information.
720 * Projects may be encouraged to instead provide this from their own
721 repository if the tooling is developed
722 * Projects choosing to meet the requirement in this way must provide a patch
723 to docs repository to import the project's documentation
725 * Projects must cooperate with the documentation group on edits and enhancements
729 Timeline for Deliverables from Projects
730 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
732 * **M2:** Documentation Started
734 The following tasks for documentation deliverables must be completed for the
737 * The kinds of documentation that will be provided and for what features must
740 .. note:: Release Notes are not required until release reviews at **RC2**
742 * The appropriate ``.rst`` files must be created in the docs repository
743 (or their own repository if the tooling is available).
744 * An outline for the expected documentation must be completed in those
745 ``.rst`` files including the relevant (sub)sections and a sentence or two
746 explaining what will be contained in these sections.
748 .. note:: If an outline is not provided, delivering actual documentation
749 in the (sub)sections meets this requirement.
751 * M2 readouts should include
753 #. the list of kinds of documentation
754 #. the list of corresponding ``.rst`` files and their location, including
756 #. the list of commits creating those ``.rst`` files
757 #. the current word counts of those ``.rst`` files
759 * **M3:** Documentation Continues
761 * The readout at M3 should include the word counts of all ``.rst`` files with
763 * The goal is to have draft documentation complete at the M3 readout so that
764 the documentation group can comment on it.
766 * **M4:** Documentation Complete
768 * All (sub)sections in all ``.rst`` files have complete, readable, usable
770 * Ideally, there should have been some interaction with the documentation
771 group about any suggested edits and enhancements
773 * **RC2:** Release notes
775 * Projects must provide release notes in ``.rst`` format pushed to integration
776 (or locally in the project's repository if the tooling is developed)
779 .. _Sphinx: https://www.sphinx-doc.org/en/master/
780 .. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
781 .. _Documentation Group: https://wiki-archive.opendaylight.org/view/Documentation/
782 .. _RelEng/Builder: https://wiki-archive.opendaylight.org/view/RelEng/Builder
783 .. _Pandoc: http://pandoc.org/