Merge "Infrautils Release notes"
[docs.git] / docs / documentation.rst
1 .. _documentation-guide:
2
3 ###################
4 Documentation Guide
5 ###################
6
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.
13
14 .. contents:: Contents
15    :depth: 2
16    :local:
17
18 Style Guide
19 ===========
20
21 This section serves two purposes:
22
23 #. A guide for those writing documentation.
24 #. A guide for those reviewing documentation.
25
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.
29
30 Formatting Preferences
31 ----------------------
32
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
37 Gerrit:
38
39 * No trailing whitespace
40 * Line wrapping at something reasonable, that is, 72–100 characters
41
42 Key terms
43 ---------
44
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
48   provide functionality
49 * OpenDaylight: this refers to the software we release; use this in
50   place of OpenDaylight controller, the OpenDaylight controller, not
51   ODL, not ODC
52
53   * Since there is a controller project within OpenDaylight, using
54     other terms is hard.
55
56 Common writing style mistakes
57 -----------------------------
58
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
62   <something>``
63 * Avoid statements which are true about part of OpenDaylight, but not
64   generally true.
65
66   * For example: "OpenDaylight is a NETCONF controller." It is, but
67     that is not all it is.
68
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
72   project.
73
74 Grammar Preferences
75 ^^^^^^^^^^^^^^^^^^^
76
77 * Avoid contractions: Use "cannot" instead of "can't", "it is" instead of
78   "it's", and so on.
79
80 Word Choice
81 ^^^^^^^^^^^^
82
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
87           name.
88
89 * ACL: not Acl or acl
90 * API: not api
91 * ARP: not Arp or arp
92 * datastore: not data store, Data Store, or DataStore (unless it is a
93   class/object name)
94 * IPsec, not IPSEC or ipsec
95 * IPv4 or IPv6: not Ipv4, Ipv6, ipv4, ipv6, IPV4, or IPV6
96 * Karaf: not karaf
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.
103
104   .. note:: Also, avoid Opendaylight abbreviations like ODL and ODC.
105
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
114
115 .. _docs-rst:
116
117 reStructuredText-based Documentation
118 ====================================
119
120 When using reStructuredText, follow the Python documentation
121 style guidelines. See: https://docs.python.org/devguide/documenting.html
122
123 One of the best references for reStrucutedText syntax is the Sphinx
124 Primer on reStructuredText_.
125
126 To build and review the reStructuredText documentation locally, you must
127 have the following packages installed locally:
128
129 * python
130 * python-tox
131
132 .. note:: Both packages should be available in most distribution package
133           managers.
134
135 Then simply run ``tox`` and open the HTML produced by using your favorite web
136 browser as follows:
137
138 .. code-block:: bash
139
140    git clone https://git.opendaylight.org/gerrit/docs
141    cd docs
142    git submodule update --init
143    tox
144    firefox docs/_build/html/index.html
145
146 Directory Structure
147 -------------------
148
149 The directory structure for the reStructuredText documentation is
150 rooted in the ``docs`` directory inside the ``docs`` ``git``
151 repository.
152
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.
157
158 For example, here is the directory layout on June, 28th 2016::
159
160    $ tree -L 2
161    .
162    ├── Makefile
163    ├── conf.py
164    ├── documentation.rst
165    ├── getting-started-guide
166    │   ├── api.rst
167    │   ├── concepts_and_tools.rst
168    │   ├── experimental_features.rst
169    │   ├── index.rst
170    │   ├── installing_opendaylight.rst
171    │   ├── introduction.rst
172    │   ├── karaf_features.rst
173    │   ├── other_features.rst
174    │   ├── overview.rst
175    │   └── who_should_use.rst
176    ├── index.rst
177    ├── make.bat
178    ├── opendaylight-with-openstack
179    │   ├── images
180    │   ├── index.rst
181    │   ├── openstack-with-gbp.rst
182    │   ├── openstack-with-ovsdb.rst
183    │   └── openstack-with-vtn.rst
184    └── submodules
185        └── releng
186            └── builder
187
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.
192
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::
195
196    .. toctree::
197       :maxdepth: 1
198
199       getting-started-guide/index
200       opendaylight-with-openstack/index
201       submodules/releng/builder/docs/index
202
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.
205
206 .. note:: When including ``.rst`` files using the ``toctree`` directive, omit
207           the ``.rst`` file extension at the end of the file name.
208
209 Adding a submodule
210 ^^^^^^^^^^^^^^^^^^
211
212 If you want to import a project underneath the documentation project so
213 that the docs can be kept in the separate repo, you can do it by using the
214 ``git submodule add`` command as follows::
215
216   git submodule add -b master ../integration/packaging docs/submodules/integration/packaging
217   git commit -s
218
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.
222
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::
226
227             <edit the .gitmodules file>
228             git add .gitmodules
229             git commit --amend
230
231 When you're done you should have a git commit something like::
232
233   $ git show
234   commit 7943ce2cb41cd9d36ce93ee9003510ce3edd7fa9
235   Author: Daniel Farrell <dfarrell@redhat.com>
236   Date:   Fri Dec 23 14:45:44 2016 -0500
237
238       Add Int/Pack to git submodules for RTD generation
239
240       Change-Id: I64cd36ca044b8303cb7fc465b2d91470819a9fe6
241       Signed-off-by: Daniel Farrell <dfarrell@redhat.com>
242
243   diff --git a/.gitmodules b/.gitmodules
244   index 91201bf6..b56e11c8 100644
245   --- a/.gitmodules
246   +++ b/.gitmodules
247   @@ -38,3 +38,7 @@
248           path = docs/submodules/ovsdb
249           url = ../ovsdb
250           branch = .
251   +[submodule "docs/submodules/integration/packaging"]
252   +       path = docs/submodules/integration/packaging
253   +       url = ../integration/packaging
254   +       branch = master
255   diff --git a/docs/submodules/integration/packaging b/docs/submodules/integration/packaging
256   new file mode 160000
257   index 00000000..fd5a8185
258   --- /dev/null
259   +++ b/docs/submodules/integration/packaging
260   @@ -0,0 +1 @@
261   +Subproject commit fd5a81853e71d45945471d0f91bbdac1a1444386
262
263 As usual, you can push it to Gerrit with ``git review``.
264
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
268                for you.
269
270 Documentation Layout and Style
271 ------------------------------
272
273 As mentioned previously, OpenDaylight aims to follow the Python documentation
274 style guidelines, which defines a few types of sections::
275
276     # with overline, for parts
277     * with overline, for chapters
278     =, for sections
279     -, for subsections
280     ^, for subsubsections
281     ", for paragraphs
282
283 OpenDaylight documentation is organized around the following structure based on
284 that recommendation::
285
286     docs/index.rst                 -> entry point
287     docs/____-guide/index.rst      -> part
288     docs/____-guide/<chapter>.rst  -> chapter
289
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::
295
296     =, for sections
297     -, for subsections
298     ^, for subsubsections
299     ", for paragraphs
300
301 Referencing Sections
302 ^^^^^^^^^^^^^^^^^^^^
303
304 This section provides a quick primer for creating references
305 in OpenDaylight documentation. For more information, refer to
306 `Cross-referencing documents
307 <http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.
308
309 Within a single document, you can reference another section simply by::
310
311    This is a reference to `The title of a section`_
312
313 Assuming that somewhere else in the same file, there a is a section
314 title something like::
315
316    The title of a section
317    ^^^^^^^^^^^^^^^^^^^^^^
318
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::
322
323    .. _a-label:
324
325    The title of a section
326    ^^^^^^^^^^^^^^^^^^^^^^
327
328 .. note:: The underscore (_) before the label is required.
329
330 Then you can reference the section anywhere by simply doing::
331
332     This is a reference to :ref:`a-label`
333
334 or::
335
336     This is a reference to :ref:`a section I really liked <a-label>`
337
338
339 .. note:: When using ``:ref:``-style links, you don't need a trailing
340           underscore (_).
341
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``.
345
346
347 .. _docs-rst-troubleshooting:
348
349 Troubleshooting
350 ---------------
351
352 Nested formatting does not work
353 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
354
355 As stated in the reStructuredText_ guide, inline markup for bold,
356 italic, and fixed-width font cannot be nested. Furthermore, inline markup cannot
357 be mixed with hyperlinks, so you cannot have a link with bold text.
358
359 This is tracked in a `Docutils FAQ question
360 <http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible>`_,
361 but there is no clear current plan to fix this.
362
363 Make sure you have cloned submodules
364 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
365
366 If you see an error like this::
367
368    ./build-integration-robot-libdoc.sh: line 6: cd: submodules/integration/test/csit/libraries: No such file or directory
369    Resource file '*.robot' does not exist.
370
371 It means that you have not pulled down the git submodule for the
372 integration/test project. The fastest way to do that is::
373
374    git submodule update --init
375
376 In some cases, you might wind up with submodules which are somehow
377 out-of-sync. In that case, the easiest way to fix them is to delete the
378 submodules directory and then re-clone the submodules::
379
380    rm -rf docs/submodules/
381    git submodule update --init
382
383 .. warning:: These steps delete any local changes or information you made
384              in the submodules, which would only occur if you
385              manually edited files in that directory.
386
387 Clear your tox directory and try again
388 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
389
390 Sometimes, tox will not detect when your ``requirements.txt`` file has
391 changed and so will try to run things without the correct dependencies.
392 This issue usually manifests  as ``No module named X`` errors or
393 an ``ExtensionError`` and can be fixed by deleting the ``.tox``
394 directory and building again::
395
396    rm -rf .tox
397    tox
398
399 Builds on Read the Docs
400 ^^^^^^^^^^^^^^^^^^^^^^^
401
402 Read the Docs builds do not automatically clear the file structure between
403 builds and clones. The result is that you may have to clean up the state of
404 old runs of the build script.
405
406 As an example, refer to the following patch:
407 https://git.opendaylight.org/gerrit/41679
408
409 This patch fixed the issue that caused builds to fail because they were
410 taking too long removing directories associated with generated
411 javadoc files that were present from previous runs.
412
413 Errors from Coala
414 ^^^^^^^^^^^^^^^^^^
415
416 As part of running ``tox``, two environments run: ``coala`` which does a variety
417 of reStructuredText_ (and other) linting, and ``docs``, which runs Sphinx_ to
418 build HTML and PDF documentation. You can run them independently by doing
419 ``tox -ecoala`` or ``tox -edocs``.
420
421 The ``coala`` linter for reStructuredText is not always the most helpful in
422 explaining why it failed. So, here are some common ones. There should also be
423 Jenkins Failure Cause Management rules that will highlight these for you.
424
425 Git Commit Message Errors
426 """""""""""""""""""""""""
427
428 Coala checks that git commit messages adhere to the following rules:
429
430 * Shortlog (1st line of commit message) is less than 50 characters
431 * Shortlog (1st line of commit message) is in the imperative mood. For example,
432   "Add foo unit test" is good, but "Adding foo unit test is bad""
433 * Body (all lines but 1st line of commit message) are less than 72 characters.
434   Some exceptions seem to exist, such as for long URLs.
435
436 Some examples of those being logged are:
437
438 ::
439    Project wide:
440    |    | [NORMAL] GitCommitBear:
441    |    | Shortlog of HEAD commit isn't in imperative mood! Bad words are 'Adding'
442
443 ::
444    Project wide:
445    |    | [NORMAL] GitCommitBear:
446    |    | Body of HEAD commit contains too long lines. Commit body lines should not exceed 72 characters.
447
448 Error in "code-block" directive
449 """""""""""""""""""""""""""""""
450
451 If you see an error like this:
452
453 ::
454    docs/gerrit.rst
455    |  89| ···..·code-block::·bash
456    |    | [MAJOR] RSTcheckBear:
457    |    | (ERROR/3) Error in "code-block" directive:
458
459 It means that the relevant code-block is not valid for the
460 language specified, in this case ``bash``.
461
462 .. note:: If you do not specify a language, the default language is Python. If
463           you want the code-block to not be an any particular language, instead
464           use the ``::`` directive. For example:
465
466 ::
467    ::
468       This is a code block
469       that will not be parsed
470       in any particluar langauge
471
472 Project Documentation Requirements
473 ==================================
474
475 Submitting Documentation Outlines (M2)
476 --------------------------------------
477
478 #. Determine the features your project will have and which ones will be
479    ''user-facing''.
480
481    * In general, a feature is user-facing if it creates functionality that a
482      user would directly interact with.
483    * For example, ``odl-openflowplugin-flow-services-ui`` is likely
484      user-facing since it installs user-facing OpenFlow features, while
485      ``odl-openflowplugin-flow-services`` is not because it provides only
486      developer-facing features.
487
488 #. Determine pieces of documentation that you need to provide based on the
489    features your project will have and which ones will be user-facing.
490
491    * The kinds of required documentation can be found below in the
492      :ref:`requirements-for-projects` section.
493
494    .. note:: You might need to create multiple documents for the
495              same kind of documentation. For example, the controller project
496              will likely want to have a developer section for the config
497              subsystem as well as for the MD-SAL.
498
499 #. Clone the docs repo: ``git clone https://git.opendaylight.org/gerrit/docs``
500 #. For each piece of documentation find the corresponding template in the docs
501    repo.
502
503    * For user documentation: ``docs.git/docs/templates/template-user-guide.rst``
504    * For developer documentation: ``ddocs/templates/template-developer-guide.rst``
505    * For installation documentation (if any): ``docs/templates/template-install-guide.rst``
506
507    .. note:: You can find the rendered templates here:
508
509              .. toctree::
510                 :maxdepth: 1
511
512                 templates/template-user-guide
513                 templates/template-developer-guide
514                 templates/template-install-guide.rst
515
516
517 #. Copy the template into the appropriate directory for your project.
518
519    * For user documentation: ``docs.git/docs/user-guide/${feature-name}-user-guide.rst``
520    * For developer documentation: ``docs.git/docs/developer-guide/${feature-name}-developer-guide.rst``
521    * For installation documentation (if any): ``docs.git/docs/getting-started-guide/project-specific-guides/${project-name}.rst``
522
523    .. note:: These naming conventions are not set in stone, but are used to
524              maintain a consistent document taxonomy. If these conventions
525              are not appropriate or do not make sense for a document
526              in development, use the convention that you think is more
527              appropriate and the documentation team will review it and give
528              feedback on the gerrit patch.
529
530 #. Edit the template to fill in the outline of what you will provide using the
531    suggestions in the template. If you feel like a section is not needed, feel
532    free to omit it.
533
534 #. Link the template into the appropriate core ``.rst`` file.
535
536    * For user documentation: ``docs.git/docs/user-guide/index.rst``
537    * For developer documentation: ``docs.git/docs/developer-guide/index.rst``
538    * For installation documentation (if any): ``docs.git/docs/getting-started-guide/project-specific-guides/index.rst``
539    * In each file, it should be pretty clear what line you need to add. In
540      general if you have an ``.rst`` file ``project-name.rst``, you include it
541      by adding a new line ``project-name`` without the ``.rst`` at the end.
542
543 #. Make sure the documentation project still builds.
544
545    * Run ``tox`` from the root of the cloned docs repo.
546
547      * After that, you should be able to find the HTML version of the
548        docs at ``docs.git/docs/_build/html/index.html``.
549      * See :ref:`docs-rst` for more details about building the docs.
550
551    * The :ref:`reStructuredText Troubleshooting <docs-rst-troubleshooting>`
552      section provides common errors and solutions.
553    * If you still have problems e-mail the documentation group at
554      documentation@lists.opendaylight.org
555
556 #. Commit and submit the patch.
557
558    #. Commit using:
559
560       .. code-block:: bash
561
562          git add --all && git commit -sm "Documentation outline for ${project-shortname}"
563
564    #. Submit using:
565
566       .. code-block:: bash
567
568          git review
569
570       See the `Git-review Workflow <https://wiki.opendaylight.org/view/Git-review_Workflow>`_
571       page if you don't have git-review installed.
572
573 #. Wait for the patch to be merged or to get feedback
574
575    * If you get feedback, make the requested changes and resubmit the patch.
576    * When you resubmit the patch, it is helpful if you also post a "+0" reply to
577      the patch in Gerrit, stating what patch set you just submitted and what you
578      fixed in the patch set.
579
580 Expected Output From Documentation Project
581 ------------------------------------------
582
583 The expected output is (at least) 3 PDFs and equivalent web-based documentation:
584
585 * User/Operator Guide
586 * Developer Guide
587 * Installation Guide
588
589 These guides will consist of "front matter" produced by the documentation group
590 and the per-project/per-feature documentation provided by the projects.
591
592 .. note:: This requirement is intended for the person responsible for the
593           documentation and should not be interpreted as preventing people not
594           normally in the documentation group from helping with front matter
595           nor preventing people from the documentation group from helping with
596           per-project/per-feature documentation.
597
598 Project Documentation Requirements
599 ----------------------------------
600
601 .. _kinds-of-docs:
602
603 Content Types
604 ^^^^^^^^^^^^^
605
606 These are the expected kinds of documentation and target audiences for each
607 kind.
608
609 * **User/Operator:** for people looking to use the feature without writing code
610
611   * Should include an overview of the project/feature
612   * Should include description of availble configuration options and what they
613     do
614
615 * **Developer:** for people looking to use the feature in code without modifying
616   it
617
618   * Should include API documentation, such as, enunciate for REST, Javadoc for
619     Java, ??? for RESTCONF/models
620
621 * **Contributor:** for people looking to extend or modify the feature's source
622   code
623
624   .. note:: You can find this information on the wiki.
625
626 * **Installation:** for people looking for instructions to install the feature
627   after they have downloaded the ODL release
628
629   .. note:: The audience for this content is the same as User/Operator docs
630
631   * For most projects, this will be just a list of top-level features and
632     options
633
634     * As an example, l2switch-switch as the top-level feature with the -rest
635       and -ui options
636     * Features should also note if the options should be checkboxes (that is,
637       they can each be turned on/off independently) or a drop down (that is, at
638       most one can be selected)
639     * What other top-level features in the release are incompatible with each
640       feature
641     * This will likely be presented as a table in the documentation and the
642       data will likely also be consumed by automated
643       installers/configurators/downloaders
644
645   * For some projects, there is extra installation instructions (for external
646     components) and/or configuration
647
648     * In that case, there will be a (sub)section in the documentation
649       describing this process.
650
651 * **HowTo/Tutorial:** walk throughs and examples that are not general-purpose
652   documentation
653
654   * Generally, these should be done as a (sub)section of either user/operator
655     or developer documentation.
656   * If they are especially long or complex, they may belong on their own
657
658 * **Release Notes:**
659
660   * Release notes are required as part of each project's release review. They
661     must also be translated into reStructuredText for inclusion in the formal
662     documentation.
663
664 .. _requirements-for-projects:
665
666 Requirements for projects
667 ^^^^^^^^^^^^^^^^^^^^^^^^^
668
669 * Projects must provide reStructuredText documentation including:
670
671   * Developer documentation for every feature
672
673     * Most projects will want to logically nest the documentation for
674       individual features under a single project-wide chapter or section
675     * The feature documentation can be provided as a single ``.rst`` file or
676       multiple ``.rst`` files if the features fall into different groups
677     * Feature documentation should start with appromimately 300 word overview
678       of the project and include references to any automatically-generated API
679       documentation as well as more general developer information (see
680       :ref:`kinds-of-docs`).
681
682   * User/Operator documentation for every every user-facing feature (if any)
683
684     * This documentation should be per-feature, not per-project. Users should
685       not have to know which project a feature came from.
686     * Intimately related features can be documented together. For example,
687       l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be
688       documented as one noting the differences.
689     * This documentation can be provided as a single ``.rst`` file or multiple
690       ``.rst`` files if the features fall into different groups
691
692   * Installation documentation
693
694     * Most projects will simply provide a list of user-facing features and
695       options. See :ref:`kinds-of-docs` above.
696
697   * Release Notes (both on the wiki and reStructuredText) as part of the release
698     review.
699
700 * Documentation must be contributed to the docs repo (or possibly imported
701   from the project's own repo with tooling that is under development)
702
703   * Projects may be encouraged to instead provide this from their own
704     repository if the tooling is developed
705   * Projects choosing to meet the requirement in this way must provide a patch
706     to docs repo to import the project's documentation
707
708 * Projects must cooperate with the documentation group on edits and enhancements
709   to documentation
710
711
712 Timeline for Deliverables from Projects
713 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
714
715 * **M2:** Documentation Started
716
717   The following tasks for documentation deliverables must be completed for the
718   M2 readout:
719
720   * The kinds of documentation that will be provided and for what features must
721     be identified.
722
723     .. note:: Release Notes are not required until release reviews at **RC2**
724
725   * The appropriate ``.rst`` files must be created in the docs repository
726     (or their own repository if the tooling is available).
727   * An outline for the expected documentation must be completed in those
728     ``.rst`` files including the relevant (sub)sections and a sentence or two
729     explaining what will be contained in these sections.
730
731     .. note:: If an outline is not provided, delivering actual documentation
732               in the (sub)sections meets this requirement.
733
734   * M2 readouts should include
735
736     #. the list of kinds of documentation
737     #. the list of corresponding ``.rst`` files and their location, including
738        repo and path
739     #. the list of commits creating those ``.rst`` files
740     #. the current word counts of those ``.rst`` files
741
742 * **M3:** Documentation Continues
743
744   * The readout at M3 should include the word counts of all ``.rst`` files with
745     links to commits
746   * The goal is to have draft documentation complete at the M3 readout so that
747     the documentation group can comment on it.
748
749 * **M4:** Documentation Complete
750
751   * All (sub)sections in all ``.rst`` files have complete, readable, usable
752     content.
753   * Ideally, there should have been some interaction with the documentation
754     group about any suggested edits and enhancements
755
756 * **RC2:** Release notes
757
758   * Projects must provide release notes in ``.rst`` format pushed to integration
759     (or locally in the project's repository if the tooling is developed)
760
761
762 .. _Sphinx: http://www.sphinx-doc.org/en/stable/
763 .. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html
764 .. _Documentation Group: https://wiki.opendaylight.org/view/Documentation/
765 .. _RelEng/Builder: https://wiki.opendaylight.org/view/RelEng/Builder
766 .. _Pandoc: http://pandoc.org/