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
239 It's pretty common to want to reference another location in the
240 OpenDaylight documentation and it's pretty easy to do with
241 reStructuredText. This is a quick primer, more information is in the
242 `Sphinx section on Cross-referencing arbitrary locations
243 <http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.
245 Within a single document, you can reference another section simply by::
247 This is a reference to `The title of a section`_
249 Assuming that somewhere else in the same file there a is a section
250 title something like::
252 The title of a section
253 ^^^^^^^^^^^^^^^^^^^^^^
255 It's typically better to use ``:ref:`` syntax and labels to provide
256 links as they work across files and are resilient to sections being
257 renamed. First, you need to create a label something like::
261 The title of a section
262 ^^^^^^^^^^^^^^^^^^^^^^
264 .. note:: The underscore (_) before the label is required.
266 Then you can reference the section anywhere by simply doing::
268 This is a reference to :ref:`a-label`
272 This is a reference to :ref:`a section I really liked <a-label>`
274 .. note:: When using ``:ref:``-style links, you don't need a trailing
277 Because the labels have to be unique, it usually makes sense to prefix
278 the labels with the project name to help share the label space, e.g.,
279 ``sfc-user-guide`` instead of just ``user-guide``.
284 Nested formatting doesn't work
285 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
287 As stated in the reStructuredText_ guide, inline markup for bold,
288 italic, and fixed-width can't be nested. Further, it can't be mixed
289 with hyperlinks, so you can't have bold text link somewhere.
291 This is tracked in a `Docutils FAQ question
292 <http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible>`_,
293 but there is no clear current plan to fix this.
295 Make sure you've cloned submodules
296 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
298 If you see an error like this::
300 ./build-integration-robot-libdoc.sh: line 6: cd: submodules/integration/test/csit/libraries: No such file or directory
301 Resource file '*.robot' does not exist.
303 It means that you haven't pulled down the git submodule for the
304 integration/test project. The fastest way to do that is::
306 git submodule update --init
308 In some cases, you might wind up with submodules which are somehow
309 out-of-sync and in that case, the easiest way to fix it is delete the
310 submodules directory and then re-clone the submodules::
312 rm -rf docs/submodules/
313 git submodule update --init
315 .. warning:: This will delete any local changes or information you made
316 in the submodules. This should only be the case if you
317 manually edited files in that directory.
319 Make sure you run tox -edocs
320 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
322 If you see an error like::
324 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)
325 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)
327 It usually means you ran `tox` and not `tox -edocs`, which will result
328 in running jobs inside submodules which aren't supported by the
329 environment defined by the `requirements.txt` file in the documentation
330 tox setup. Just run tox -edocs and it should be fine.
332 Clear your tox directory and try again
333 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
335 Sometimes, tox will not detect when your ``requirements.txt`` file has
336 changed and so will try to run things without the correct dependencies.
337 This usually manifests as ``No module named X`` errors or
338 an ``ExtensionError`` and can be fixed by deleting the ``.tox``
339 directory and building again::
344 Builds on Read the Docs
345 ^^^^^^^^^^^^^^^^^^^^^^^
347 It appears as though the Read the Docs builds don't automatically clear
348 the file structure between builds and clones. The result is that you
349 may have to clean up the state of old runs of the build script.
351 As an example, this patch:
352 https://git.opendaylight.org/gerrit/41679
354 Finally fixed the fact that our builds for failing because they were
355 taking too long by removing directories of generated javadoc that were
356 present from previous runs.
358 AsciiDoc-based Documentation
359 ============================
361 Information on the AsciiDoc tools and build system can be found here:
362 https://wiki.opendaylight.org/view/Documentation/Tools
367 The AsciiDoc documentation is all located in the ``manuals`` directory
368 of the ``docs`` ``git`` repository. An example of the directory
369 structure on June 28th, 2016 can be seen here::
374 │ └── app_support.xml
381 ├── getting-started-guide
406 Each of the top-level directories under ``manuals`` is a whole guide by
407 itself and it contains a ``pom.xml`` file saying how to build it, a
408 ``src/main/asciidoc`` directory with AsciiDoc source files and a
409 ``src/main/resources`` directory containing images.
414 See `AsciiDoc Tips`_ on the wiki for more information.
416 Common AsciiDoc mistakes
417 ^^^^^^^^^^^^^^^^^^^^^^^^
419 See also `AsciiDoc Tips`_.
421 * Lists that get formatted incorrectly because of no blank line above
423 * Numbered lists that are formatted incorrectly and every bullet winds
426 Migration from AsciiDoc to ReStructuredText
427 ===========================================
432 In theory, Pandoc_ can convert from DocBook to reStructuredText and we
433 produce DocBook as part of our build chain from AsciiDoctor. In
434 practice, for modest-sized migrations doing things by hand works fairly
440 Converting from AsciiDoc to reStructuredText is usually pretty
441 straightforward and involves looking up the basic syntax for what you
442 want to do by looking it up in the reStructuredText_ guide.
444 The differences are usually minor and fast to change.
446 Also, because of how fast Sphinx builds, and how fast it is to refresh
447 the HTML documentation rapid iteration is very easy.
449 Bold/Italics/Verbatim Formatting
450 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
452 This is mostly minor syntax issues. In AsciiDoc you do inline
453 formatting something like this::
455 *bold* _italic_ +verbatim+ `verbatim`
457 In reStructuredText, things are slightly different::
459 **bold** *italic* ``verbatim``
464 Image formats change from something like::
466 .OpenStack Architecture
467 image::vtn/OpenStackDeveloperGuide.png["OpenStack Architecture",width=500]
471 .. figure:: images/dlux-default.png
473 A helpful regular expression for automating the replacements is
476 search: ^( *)\.(.+)\n +image::(.+)\[(.+),width=(\d+)\]
477 replace: $1.. figure:: images/dlux/$3\n$1 :width: $5\n\n$1 $2
480 Project Documentation Requirements
481 ==================================
483 Submitting Documentation Outlines (M3)
484 --------------------------------------
486 #. Determine the features your project will have and which ones will be
489 * In general, a feature is user-facing if it creates functionality that a
490 user would direction interact with.
491 * For example, ``odl-openflowplugin-flow-services-ui`` is likely
492 user-facing since it installs user-facing OpenFlow features, while
493 ``odl-openflowplugin-flow-services`` is not because it provides only
494 developer-facing features.
496 #. Determine pieces of documentation you need provide based on the features
497 your project will have and which ones will be user-facing.
499 * The kinds of required documentation can be found below in the
500 :ref:`requirements-for-projects` section.
501 * Note that you might need to create multiple different documents for the
502 same kind of documentation. For example, the controller project will
503 likely want to have a developer section for the config subsystem as well
506 #. Clone the docs repo: ``git clone https://git.opendaylight.org/gerrit/docs``
507 #. For each piece of documentation find the corresponding template in the docs repo.
509 * For user documentation: ``docs.git/manuals/readme/src/main/asciidoc/template_user_guide.adoc``
510 * For developer documentation: ``docs.git/manuals/readme/src/main/asciidoc/template_developer_guide.adoc``
511 * For installation documentation (if any): ``docs.git/manuals/readme/src/main/asciidoc/template_installation_guide.adoc``
513 #. Copy the template into the appropriate directory for your project.
515 * For user documentation: ``docs.git/manuals/user-guide/src/main/asciidoc/${project-shortname}/${feature-name}-user.adoc``
516 * For developer documentation: ``docs.git/manuals/developer-guide/src/main/asciidoc/${project-shortname}/${feature-name}-dev.adoc``
517 * For installation documentation (if any): ``docs.git/manuals/install-guide/src/main/asciidoc/${project-shortname}/${feature-name}-install.adoc``
519 #. Edit the template to fill in the outline of what you will provide using the
520 suggestions in the template.
522 * DO NOT leave any sections blank as blank sections will cause build errors.
524 #. Link the template into the appropriate core adoc file
526 * For user documentation: ``docs.git/manuals/user-guide/src/main/asciidoc/bk-user-guide.adoc``
527 * For developer documentation: ``docs.git/manuals/developer-guide/src/main/asciidoc/bk-developers-guide.adoc``
528 * For installation documentation (if any): ``docs.git/manuals/install-guide/src/main/asciidoc/bk-install-guide.adoc``
533 include::${project-shortname}/${feature-name}-user.adoc[]
535 * Make sure there is a blank line between your include statement and any others as this prevents sections from running into each other.
537 #. Make sure the documentation project still builds.
539 * Run ``mvn clean install`` from the root of the cloned docs repo.
541 * After that, you should be able to find the PDF and HTML version of the
542 docs. Use ``find . -name *.pdf`` to find the PDF and the HTML is
543 always at ``target/docbkx/webhelp/${manual-name}/index.html``.
545 * The `AsciiDoc tips <https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Tools:AsciiDoc_Tips>`_
546 page provide common errors and solutions.
547 * If you still have problems e-mail the documentation group at
548 documentation@lists.opendaylight.org
550 #. Commit and submit the patch
556 git add --all && git commit -sm "Documentation outline for ${project-shortname}"
564 See the `Git-review Workflow <https://wiki.opendaylight.org/view/Git-review_Workflow>`_
565 page if you don't have git-review installed.
567 #. Wait for the patch to be merged or to get feedback
569 * If you get feedback, make the requested changes and resubmit the patch.
570 * When you resubmit the patch, it's helpful if you also post a +0 reply to
571 the gerrit saying what patch set you just submitted and what you fixed in
573 * The documentation team will also be creating (or asking projects to
574 create) small groups of 2-4 projects that will peer review each other's
575 documentation. Patches which have seen a few cycles of peer review will be
576 prioritized for review and merge by the documentation team.
578 Expected Output From Documentation Project
579 ------------------------------------------
581 The expected output is (at least) 3 PDFs and equivalent web-based documentation:
583 * User/Operator Guide
587 These guides will consist of "front matter" produced by the documentation group
588 and the per-project/per-feature documentation provided by the projects. Note
589 that this is intended to be who is responsible for the documentation and should
590 not be interpreted as preventing people not normally in the documentation group
591 from helping with "front matter" nor preventing people from the documentation
592 group from helping with per-project/per-feature documentation.
594 Boron Project Documentation Requirements
595 ----------------------------------------
599 Kinds of Documentation
600 ^^^^^^^^^^^^^^^^^^^^^^
602 These are the expected kinds of documentation and target audiences for each kind.
604 * **User/Operator:** for people looking to use the feature w/o writing code
606 * Should include an overview of the project/feature
607 * Should include description of availbe configuration options and what they do
609 * **Developer:** for people looking to use the feature in code w/o modifying it
611 * Should include API documentation, e.g., enunciate for REST, Javadoc for
612 Java, ??? for RESTCONF/models
614 * **Contributor:** for people looking to extend or modify the feature's source
619 should be documented on the wiki not in asciidoc
621 * **Installation:** for people looking for instructions to install the feature
622 after they have downloaded the ODL release
626 audience is the same as User/Operator docs
628 * For most projects, this will be just a list of top-level features and
631 * As an example, l2switch-switch as the top-level feature with the -rest
633 * We'd also like them to note if the options should be checkboxes (i.e.,
634 they can each be turned on/off independently) or a drop down (i.e., at
635 most one can be selected)
636 * What other top-level features in the release are incompatible with each
638 * This will likely be presented as a table in the documentation and the
639 data will likely also be consumed by automated installers/configurators/downloaders
641 * For some projects, there is extra installation instructions (for external
642 components) and/or configuration
644 * In that case, there will be a (sub)section in the documentation
645 describing this process.
647 * **HowTo/Tutorial:** walk throughs and examples that are not general-purpose
650 * Generally, these should be done as a (sub)section of either user/operator
651 or developer documentation.
652 * If they are especially long or complex, they may belong on their own
656 * Release notes are required as part of each project's release review. They
657 must also be translated into AsciiDoc for inclusion in the formal
660 .. _requirements-for-projects:
662 Requirements for projects
663 ^^^^^^^^^^^^^^^^^^^^^^^^^
665 Projects MUST do the following
667 * Provide `AsciiDoc-format <https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Tools:AsciiDoc_Tips>`_ documentation including
669 * Developer documentation for every feature
671 * Most projects will want to logically nest the documentation for
672 individual features under a single project-wide chapter or section
673 * This can be provided as a single .adoc file or multiple .adoc files if
674 the features fall into different groups
675 * This should start with ~300 word overview of the project and include
676 references to any automatically-generated API documentation as well as
677 more general developer information (see
678 :ref:`kinds-of-docs`).
680 * User/Operator documentation for every every user-facing feature (if any)
682 * ''Note: This should be per-feature, not per-project. User's shouldn't have to know which project a feature came from.''
683 * Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences
684 * This can be provided as a single .adoc file or multiple .adoc files if the features fall into different groups
686 * Installation documentation
688 * Most projects will simply provide a list of user-facing features and
689 options. See :ref:`kinds-of-docs` above.
691 * Release Notes (both on the wiki and AsciiDoc) as part of the release review.
693 * This documentation will be contributed to the docs repo (or possibly imported from the project's own repo with tooling that is under development)
695 * Projects MAY be ENCOURGAGED to instead provide this from their own repository if the tooling is developed
696 * Projects choosing to meet the requirement this way MUST provide a patch to docs repo to import the project's documentation
698 * Projects MUST cooperate with the documentation group on edits and enhancements to documentation
700 * 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.
702 Timeline for Deliverables from Projects
703 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
705 * **M3:** Documentation Started
707 * Identified the kinds of documentation that will be provided and for what
710 * Release Notes are not required until release reviews at **RC2**
712 * Created the appropriate .adoc files in the docs repository (or their own
713 repository if the tooling is available)
714 * Have an outline for the expected documentation in those .adoc files
715 including the relevant (sub)sections and a sentence or two explaining what
718 * Obviusly, providing actual documentation in the (sub)sections is
719 encouraged and meets this requirement
721 * Milestone readout should include
723 #. the list of kinds of documentation
724 #. the list of corresponding .adoc files and their location, e.g., repo and
726 #. the list of commits creating those .adoc files
727 #. the current word counts of those .adoc files
729 * **M4:** Documentation Continues
731 * The readout at M4 should include the word counts of all .adoc files with
733 * The goal is to have draft documentation complete so that the documentation
734 group can comment on it.
736 * **M5:** Documentation Complete
738 * All (sub)sections in all .adoc files have complete, readable, usable content.
739 * Ideally, there should have been some interaction with the documentation
740 group about any suggested edits and enhancements
742 * **RC2:** Release notes
744 * Projects must provide release notes as .adoc pushed to integration (or
745 locally in the project's repository if the tooling is developed)
748 .. _AsciiDoc: http://www.methods.co.nz/asciidoc/
749 .. _Sphinx: http://www.sphinx-doc.org/en/stable/
750 .. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html
751 .. _Documentation Group: https://wiki.opendaylight.org/view/Documentation/
752 .. _RelEng/Builder: https://wiki.opendaylight.org/view/RelEng/Builder
753 .. _Pandoc: http://pandoc.org/
754 .. _AsciiDoc Tips: https://wiki.opendaylight.org/view/Documentation/Tools/AsciiDoc_Tips