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
144 The directory structure for the reStructuredText documentation is
145 rooted in the ``docs`` directory inside the ``docs`` ``git``
148 Below that there are guides hosted directly in the ``docs`` ``git``
149 repository and there are guides hosted in remote ``git`` repositories.
150 Usually those are for project-specific information.
152 For example here is the directory layout on June, 28th 2016::
158 ├── documentation.rst
159 ├── getting-started-guide
161 │ ├── concepts_and_tools.rst
162 │ ├── experimental_features.rst
164 │ ├── installing_opendaylight.rst
165 │ ├── introduction.rst
166 │ ├── karaf_features.rst
167 │ ├── other_features.rst
169 │ └── who_should_use.rst
172 ├── opendaylight-with-openstack
175 │ ├── openstack-with-gbp.rst
176 │ ├── openstack-with-ovsdb.rst
177 │ └── openstack-with-vtn.rst
182 The ``getting-started-guide`` and ``opendaylight-with-openstack``
183 directories correspond to two guides hosted in the ``docs`` repository,
184 while the ``submodules/releng/builder`` directory houses documentation
185 for the `RelEng/Builder`_ project.
187 Inside each guide there is usually an ``index.rst`` file which then
188 includes other files using a ``toctree`` directive. For example::
193 getting-started-guide/index
194 opendaylight-with-openstack/index
195 submodules/releng/builder/docs/index
197 This creates a table of contents on that page where each heading of the
198 table of contents is the root of the files that are included.
200 .. note:: When including rst files using ``toctree`` omit the .rst at
201 the end of the file name.
206 If you want to import a project underneath the documentation project so
207 that the docs can be kept in the separate repo, you can do it using the
208 ``git submodule add`` command as follows::
210 git submodule add -b master ../integration/packaging docs/submodules/integration/packaging
213 .. note:: Most projects will not want to use ``-b master``, but instead
214 use the branch ``.``, which will make track whatever branch
215 of the documentation project you happen to be on.
217 Unfortunately, ``-b .`` doesn't work, so you have to manually
218 edit the ``.gitmodules`` file to add ``branch = .`` and then
219 commit it. Something like::
221 <edit the .gitmodules file>
225 When you're done you should have a git commit something like::
228 commit 7943ce2cb41cd9d36ce93ee9003510ce3edd7fa9
229 Author: Daniel Farrell <dfarrell@redhat.com>
230 Date: Fri Dec 23 14:45:44 2016 -0500
232 Add Int/Pack to git submodules for RTD generation
234 Change-Id: I64cd36ca044b8303cb7fc465b2d91470819a9fe6
235 Signed-off-by: Daniel Farrell <dfarrell@redhat.com>
237 diff --git a/.gitmodules b/.gitmodules
238 index 91201bf6..b56e11c8 100644
242 path = docs/submodules/ovsdb
245 +[submodule "docs/submodules/integration/packaging"]
246 + path = docs/submodules/integration/packaging
247 + url = ../integration/packaging
249 diff --git a/docs/submodules/integration/packaging b/docs/submodules/integration/packaging
251 index 00000000..fd5a8185
253 +++ b/docs/submodules/integration/packaging
255 +Subproject commit fd5a81853e71d45945471d0f91bbdac1a1444386
257 As usual, you can push it to Gerrit with ``git review``.
259 .. important:: It's critical that the Gerrit patch be merged before the
260 git commit hash of the submodule changes. Otherwise,
261 Gerrit won't be able to automatically keep it up-to-date
264 Documentation Layout and Style
265 ------------------------------
267 As mentioned previously we try to follow the python documentation style
268 guide which defines a few types of sections::
270 # with overline, for parts
271 * with overline, for chapters
274 ^, for subsubsections
277 We try to follow the following structure based on that recommendation::
279 docs/index.rst -> entry point
280 docs/____-guide/index.rst -> part
281 docs/____-guide/<chapter>.rst -> chapter
283 In the ____-guide/index.rst we use the # with overline at the very top
284 of the file to determine that it is a part and then within each chapter
285 file we start the document with a section using * with overline to
286 denote that it's the chapter heading and then everything in the rest of
287 the chapter should use::
291 ^, for subsubsections
297 It's pretty common to want to reference another location in the
298 OpenDaylight documentation and it's pretty easy to do with
299 reStructuredText. This is a quick primer, more information is in the
300 `Sphinx section on Cross-referencing arbitrary locations
301 <http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.
303 Within a single document, you can reference another section simply by::
305 This is a reference to `The title of a section`_
307 Assuming that somewhere else in the same file there a is a section
308 title something like::
310 The title of a section
311 ^^^^^^^^^^^^^^^^^^^^^^
313 It's typically better to use ``:ref:`` syntax and labels to provide
314 links as they work across files and are resilient to sections being
315 renamed. First, you need to create a label something like::
319 The title of a section
320 ^^^^^^^^^^^^^^^^^^^^^^
322 .. note:: The underscore (_) before the label is required.
324 Then you can reference the section anywhere by simply doing::
326 This is a reference to :ref:`a-label`
330 This is a reference to :ref:`a section I really liked <a-label>`
332 .. note:: When using ``:ref:``-style links, you don't need a trailing
335 Because the labels have to be unique, it usually makes sense to prefix
336 the labels with the project name to help share the label space, e.g.,
337 ``sfc-user-guide`` instead of just ``user-guide``.
340 .. _docs-rst-troubleshooting:
345 Nested formatting doesn't work
346 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
348 As stated in the reStructuredText_ guide, inline markup for bold,
349 italic, and fixed-width can't be nested. Further, it can't be mixed
350 with hyperlinks, so you can't have bold text link somewhere.
352 This is tracked in a `Docutils FAQ question
353 <http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible>`_,
354 but there is no clear current plan to fix this.
356 Make sure you've cloned submodules
357 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
359 If you see an error like this::
361 ./build-integration-robot-libdoc.sh: line 6: cd: submodules/integration/test/csit/libraries: No such file or directory
362 Resource file '*.robot' does not exist.
364 It means that you haven't pulled down the git submodule for the
365 integration/test project. The fastest way to do that is::
367 git submodule update --init
369 In some cases, you might wind up with submodules which are somehow
370 out-of-sync and in that case, the easiest way to fix it is delete the
371 submodules directory and then re-clone the submodules::
373 rm -rf docs/submodules/
374 git submodule update --init
376 .. warning:: This will delete any local changes or information you made
377 in the submodules. This should only be the case if you
378 manually edited files in that directory.
380 Clear your tox directory and try again
381 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
383 Sometimes, tox will not detect when your ``requirements.txt`` file has
384 changed and so will try to run things without the correct dependencies.
385 This usually manifests as ``No module named X`` errors or
386 an ``ExtensionError`` and can be fixed by deleting the ``.tox``
387 directory and building again::
392 Builds on Read the Docs
393 ^^^^^^^^^^^^^^^^^^^^^^^
395 It appears as though the Read the Docs builds don't automatically clear
396 the file structure between builds and clones. The result is that you
397 may have to clean up the state of old runs of the build script.
399 As an example, this patch:
400 https://git.opendaylight.org/gerrit/41679
402 Finally fixed the fact that our builds for failing because they were
403 taking too long by removing directories of generated javadoc that were
404 present from previous runs.
406 Weird Errors from Coala
407 ^^^^^^^^^^^^^^^^^^^^^^^
409 As pat of running ``tox``, two environments run: ``coala`` which does a variety
410 of reStructuredText_ (and other) linting, and ``docs``, which runs Sphinx_ to
411 build HTML and PDF documentation. You can run them independently by doing
412 ``tox -ecoala`` or ``tox -edocs``.
414 The ``coala`` linter for reStructuredText isn't always the most helpful in
415 explaining why it failed. So, here are some common ones. There should also be
416 Jenkins Failure Cause Management rules that will highlight these for you.
418 Git Commit Message Errors
419 """""""""""""""""""""""""
421 Coala will check git commit messages for a variety of things including
423 * Shortlog (1st line of commit message) is less than 50 characters
424 * Shortlog (1st line of commit message) is in the imperative mood, e.g., "Add
425 foo unit test" is good, but "Adding foo unit test is bad""
426 * Body (all lines but 1st line of commit message) are less than 72 characters.
427 Some exceptions seem to exist, e.g., for long URLs.
429 Some examples of those being logged are:
433 | | [NORMAL] GitCommitBear:
434 | | Shortlog of HEAD commit isn't in imperative mood! Bad words are 'Adding'
438 | | [NORMAL] GitCommitBear:
439 | | Body of HEAD commit contains too long lines. Commit body lines should not exceed 72 characters.
441 Error in "code-block" directive
442 """""""""""""""""""""""""""""""
444 If you see an error like this:
448 | 89| ···..·code-block::·bash
449 | | [MAJOR] RSTcheckBear:
450 | | (ERROR/3) Error in "code-block" directive:
452 It seems to mean that the relevant code-block does is not valid for the
453 language specified, in this case bash. Note that if you specify no language, it
454 seems as though it assumes the language is python. If you want the code-block
455 to not be an any particular language, instead use the ``::`` directive. For
461 that will not be parsed
462 in any particluar langauge
464 Project Documentation Requirements
465 ==================================
467 Submitting Documentation Outlines (M3)
468 --------------------------------------
470 #. Determine the features your project will have and which ones will be
473 * In general, a feature is user-facing if it creates functionality that a
474 user would direction interact with.
475 * For example, ``odl-openflowplugin-flow-services-ui`` is likely
476 user-facing since it installs user-facing OpenFlow features, while
477 ``odl-openflowplugin-flow-services`` is not because it provides only
478 developer-facing features.
480 #. Determine pieces of documentation you need provide based on the features
481 your project will have and which ones will be user-facing.
483 * The kinds of required documentation can be found below in the
484 :ref:`requirements-for-projects` section.
485 * Note that you might need to create multiple different documents for the
486 same kind of documentation. For example, the controller project will
487 likely want to have a developer section for the config subsystem as well
490 #. Clone the docs repo: ``git clone https://git.opendaylight.org/gerrit/docs``
491 #. For each piece of documentation find the corresponding template in the docs repo.
493 * For user documentation: ``docs.git/docs/templates/template-user-guide.rst``
494 * For developer documentation: ``ddocs/templates/template-developer-guide.rst``
495 * For installation documentation (if any): ``docs/templates/template-install-guide.rst``
497 .. note:: You can find the rendered templates here:
502 templates/template-user-guide
503 templates/template-developer-guide
504 templates/template-install-guide.rst
507 #. Copy the template into the appropriate directory for your project.
509 * For user documentation: ``docs.git/docs/user-guide/${feature-name}-user-guide.rst``
510 * For developer documentation: ``docs.git/docs/developer-guide/${feature-name}-developer-guide.rst``
511 * For installation documentation (if any): ``docs.git/docs/getting-started-guide/project-specific-guides/${project-name}.rst``
513 .. note:: These naming conventions aren't set in stone, but do help. If you
514 think there's a better name, use it and we'll give feedback on the
517 #. Edit the template to fill in the outline of what you will provide using the
518 suggestions in the template. If you feel like a section isn't needed, feel
521 #. Link the template into the appropriate core rst file
523 * For user documentation: ``docs.git/docs/user-guide/index.rst``
524 * For developer documentation: ``docs.git/docs/developer-guide/index.rst``
525 * For installation documentation (if any): ``docs.git/docs/getting-started-guide/project-specific-guides/index.rst``
526 * In each file, it should be pretty clear what line you need to add. In
527 general if you have an rst file ``project-name.rst``, you include it by
528 adding a new line ``project-name`` without the ``.rst`` at the end.
530 #. Make sure the documentation project still builds.
532 * Run ``tox`` from the root of the cloned docs repo.
534 * After that, you should be able to find the HTML version of the
535 docs at ``docs.git/docs/_build/html/index.html``.
536 * See :ref:`docs-rst` for more details about building the docs.
538 * The :ref:`reStructuredText Troubleshooting <docs-rst-troubleshooting>`
539 section provides common errors and solutions.
540 * If you still have problems e-mail the documentation group at
541 documentation@lists.opendaylight.org
543 #. Commit and submit the patch
549 git add --all && git commit -sm "Documentation outline for ${project-shortname}"
557 See the `Git-review Workflow <https://wiki.opendaylight.org/view/Git-review_Workflow>`_
558 page if you don't have git-review installed.
560 #. Wait for the patch to be merged or to get feedback
562 * If you get feedback, make the requested changes and resubmit the patch.
563 * When you resubmit the patch, it's helpful if you also post a +0 reply to
564 the gerrit saying what patch set you just submitted and what you fixed in
566 * The documentation team will also be creating (or asking projects to
567 create) small groups of 2-4 projects that will peer review each other's
568 documentation. Patches which have seen a few cycles of peer review will be
569 prioritized for review and merge by the documentation team.
571 Expected Output From Documentation Project
572 ------------------------------------------
574 The expected output is (at least) 3 PDFs and equivalent web-based documentation:
576 * User/Operator Guide
580 These guides will consist of "front matter" produced by the documentation group
581 and the per-project/per-feature documentation provided by the projects. Note
582 that this is intended to be who is responsible for the documentation and should
583 not be interpreted as preventing people not normally in the documentation group
584 from helping with "front matter" nor preventing people from the documentation
585 group from helping with per-project/per-feature documentation.
587 Boron Project Documentation Requirements
588 ----------------------------------------
592 Kinds of Documentation
593 ^^^^^^^^^^^^^^^^^^^^^^
595 These are the expected kinds of documentation and target audiences for each kind.
597 * **User/Operator:** for people looking to use the feature w/o writing code
599 * Should include an overview of the project/feature
600 * Should include description of availbe configuration options and what they do
602 * **Developer:** for people looking to use the feature in code w/o modifying it
604 * Should include API documentation, e.g., enunciate for REST, Javadoc for
605 Java, ??? for RESTCONF/models
607 * **Contributor:** for people looking to extend or modify the feature's source
612 should be documented on the wiki not in reStructuredText
614 * **Installation:** for people looking for instructions to install the feature
615 after they have downloaded the ODL release
619 audience is the same as User/Operator docs
621 * For most projects, this will be just a list of top-level features and
624 * As an example, l2switch-switch as the top-level feature with the -rest
626 * We'd also like them to note if the options should be checkboxes (i.e.,
627 they can each be turned on/off independently) or a drop down (i.e., at
628 most one can be selected)
629 * What other top-level features in the release are incompatible with each
631 * This will likely be presented as a table in the documentation and the
632 data will likely also be consumed by automated installers/configurators/downloaders
634 * For some projects, there is extra installation instructions (for external
635 components) and/or configuration
637 * In that case, there will be a (sub)section in the documentation
638 describing this process.
640 * **HowTo/Tutorial:** walk throughs and examples that are not general-purpose
643 * Generally, these should be done as a (sub)section of either user/operator
644 or developer documentation.
645 * If they are especially long or complex, they may belong on their own
649 * Release notes are required as part of each project's release review. They
650 must also be translated into reStructuredText for inclusion in the formal
653 .. _requirements-for-projects:
655 Requirements for projects
656 ^^^^^^^^^^^^^^^^^^^^^^^^^
658 Projects MUST do the following
660 * Provide reStructuredText documentation including
662 * Developer documentation for every feature
664 * Most projects will want to logically nest the documentation for
665 individual features under a single project-wide chapter or section
666 * This can be provided as a single .rst file or multiple .rst files if
667 the features fall into different groups
668 * This should start with ~300 word overview of the project and include
669 references to any automatically-generated API documentation as well as
670 more general developer information (see
671 :ref:`kinds-of-docs`).
673 * User/Operator documentation for every every user-facing feature (if any)
675 * ''Note: This should be per-feature, not per-project. User's shouldn't have to know which project a feature came from.''
676 * Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences
677 * This can be provided as a single .rst file or multiple .rst files if the features fall into different groups
679 * Installation documentation
681 * Most projects will simply provide a list of user-facing features and
682 options. See :ref:`kinds-of-docs` above.
684 * Release Notes (both on the wiki and reStructuredText) as part of the release review.
686 * This documentation will be contributed to the docs repo (or possibly imported from the project's own repo with tooling that is under development)
688 * Projects MAY be ENCOURGAGED to instead provide this from their own repository if the tooling is developed
689 * Projects choosing to meet the requirement this way MUST provide a patch to docs repo to import the project's documentation
691 * Projects MUST cooperate with the documentation group on edits and enhancements to documentation
693 * 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.
695 Timeline for Deliverables from Projects
696 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
698 * **M3:** Documentation Started
700 * Identified the kinds of documentation that will be provided and for what
703 * Release Notes are not required until release reviews at **RC2**
705 * Created the appropriate .rst files in the docs repository (or their own
706 repository if the tooling is available)
707 * Have an outline for the expected documentation in those .rst files
708 including the relevant (sub)sections and a sentence or two explaining what
711 * Obviusly, providing actual documentation in the (sub)sections is
712 encouraged and meets this requirement
714 * Milestone readout should include
716 #. the list of kinds of documentation
717 #. the list of corresponding .rst files and their location, e.g., repo and
719 #. the list of commits creating those .rst files
720 #. the current word counts of those .rst files
722 * **M4:** Documentation Continues
724 * The readout at M4 should include the word counts of all .rst files with
726 * The goal is to have draft documentation complete so that the documentation
727 group can comment on it.
729 * **M5:** Documentation Complete
731 * All (sub)sections in all .rst files have complete, readable, usable content.
732 * Ideally, there should have been some interaction with the documentation
733 group about any suggested edits and enhancements
735 * **RC2:** Release notes
737 * Projects must provide release notes as .rst pushed to integration (or
738 locally in the project's repository if the tooling is developed)
741 .. _Sphinx: http://www.sphinx-doc.org/en/stable/
742 .. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html
743 .. _Documentation Group: https://wiki.opendaylight.org/view/Documentation/
744 .. _RelEng/Builder: https://wiki.opendaylight.org/view/RelEng/Builder
745 .. _Pandoc: http://pandoc.org/