Updated git submodules

[docs.git] / docs / documentation.rst

.. _documentation-guide:

###################
Documentation Guide
###################

This guide provides details on how to contribute to the OpenDaylight
documentation. OpenDaylight currently uses reStructuredText_ for
documentation and Sphinx_ to build it as it is widely-used to provide
both HTML and pdf documentation that can be easily versioned alongside
the code. It also offers similar syntax to Markdown which is familiar
to large numbers of people.

.. contents:: Contents
   :depth: 2
   :local:

Style Guide
===========

This section serves two purposes:

#. A guide for those writing documentation to follow.
#. A guide for those reviewing documentation.

That being said, assuming that the content is usable, the bias should
be toward merging it rather than blocking on relatively minor edits.

Formatting Preferences
----------------------

In general, the documentation team has focused on trying to make sure
that the instructions are comprehensible, but not being overly pedantic
about these things. Along those lines, while we would prefer the
following, generally they aren't a reason to -1 in and of themselves:

* No trailing whitespace
* Line wrapping at something reasonable, i.e., 72–100 characters

Key terms
---------

* Functionality: something useful a project provides abstractly
* Feature: a Karaf feature that somebody could install
* Project: a project within OpenDaylight, projects ship features to
  provide functionality
* OpenDaylight: this refers to the software we release, use this in
  place of OpenDaylight controller, the OpenDaylight controller, not
  ODL, not ODC

  * Since there is a controller project within OpenDaylight, using
    other terms is hard.

Common writing style mistakes
-----------------------------

* In per-project user documentation, you should never say *git clone*,
  but should assume people have downloaded and installed the controller
  per the getting started guide and start with ``feautre:install
  <something>``
* Avoid statements which are true about part of OpenDaylight, but not
  generally true.

  * For example: "OpenDaylight is a NETCONF controller." It is, but
    that is not all it is.

* In general, developer documentation should target external developers
  to your project so should talk about what APIs you have and how they
  could use them. It *should not* document how to contribute to your
  project.

Grammar Preferences
^^^^^^^^^^^^^^^^^^^

* Avoid contractions: use cannot instead of can't, it is instead of
  it's, and the like.

Things to get right with spacing and capitalization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Note that all of these apply when using them in text. If they are used
as part of URL, class name, or something similar, use the actual
capitalization and spacing.*

* ACL: not Acl or acl
* API: not api
* ARP: not Arp or arp
* datastore: not data store, Data Store, or DataStore (unless it's a
  class/object name)
* IPsec, not IPSEC or ipsec
* IPv4 or IPv6: not Ipv4, Ipv6, ipv4, ipv6, IPV4, or IPV6
* Karaf: not karaf
* Linux: not LINUX or linux
* NETCONF: not Netconf or netconf
* Neutron: not neutron
* OSGi: not osgi or OSGI
* Open vSwitch: not OpenvSwitch, OpenVSwitch, or Open V Switch, etc.
* OpenDaylight: not Opendaylight, Open Daylight, or OpenDayLight, etc.

  * also avoid abbreviations like ODL and ODC

* OpenFlow: not Openflow, Open Flow, openflow, etc.
* OpenStack: not Open Stack or Openstack
* QoS: not Qos, QOS, or qos
* RESTCONF: not Restconf or restconf
* RPC not Rpc or rpc
* URL not Url or url
* VM: not Vm or vm
* YANG: not Yang or yang

.. _docs-rst:

reStructuredText-based Documentation
====================================

When using reStructuredText, we try to follow the python documentation
style guide. See: https://docs.python.org/devguide/documenting.html

The best reference for reStrucutedText syntax seems to be the Sphinx
Primer on reStructuredText_.

To build and review the reStructuredText documentation locally you must
have installed locally:

* python
* python-tox

Which both should be available in most distribution's package managers.

Then simply run tox and open the html produced via your favorite web
browser as follows:

.. code-block:: bash

   git clone https://git.opendaylight.org/gerrit/docs
   cd docs
   git submodule update --init
   tox
   firefox docs/_build/html/index.html

Directory Structure
-------------------

The directory structure for the reStructuredText documentation is
rooted in the ``docs`` directory inside the ``docs`` ``git``
repository.

Below that there are guides hosted directly in the ``docs`` ``git``
repository and there are guides hosted in remote ``git`` repositories.
Usually those are for project-specific information.

For example here is the directory layout on June, 28th 2016::

   $ tree -L 2
   .
   ├── Makefile
   ├── conf.py
   ├── documentation.rst
   ├── getting-started-guide
   │   ├── api.rst
   │   ├── concepts_and_tools.rst
   │   ├── experimental_features.rst
   │   ├── index.rst
   │   ├── installing_opendaylight.rst
   │   ├── introduction.rst
   │   ├── karaf_features.rst
   │   ├── other_features.rst
   │   ├── overview.rst
   │   └── who_should_use.rst
   ├── index.rst
   ├── make.bat
   ├── opendaylight-with-openstack
   │   ├── images
   │   ├── index.rst
   │   ├── openstack-with-gbp.rst
   │   ├── openstack-with-ovsdb.rst
   │   └── openstack-with-vtn.rst
   └── submodules
       └── releng
           └── builder

The ``getting-started-guide`` and ``opendaylight-with-openstack``
directories correspond to two guides hosted in the ``docs`` repository,
while the ``submodules/releng/builder`` directory houses documentation
for the `RelEng/Builder`_ project.

Inside each guide there is usually an ``index.rst`` file which then
includes other files using a ``toctree`` directive. For example::

   .. toctree::
      :maxdepth: 1

      getting-started-guide/index
      opendaylight-with-openstack/index
      submodules/releng/builder/docs/index

This creates a table of contents on that page where each heading of the
table of contents is the root of the files that are included.

.. note:: When including rst files using ``toctree`` omit the .rst at
          the end of the file name.

Adding a submodule
^^^^^^^^^^^^^^^^^^

If you want to import a project underneath the documentation project so
that the docs can be kept in the separate repo, you can do it using the
``git submodule add`` command as follows::

  git submodule add -b master ../integration/packaging docs/submodules/integration/packaging
  git commit -s

.. note:: Most projects will not want to use ``-b master``, but instead
          use the branch ``.``, which will make track whatever branch
          of the documentation project you happen to be on.

          Unfortunately, ``-b .`` doesn't work, so you have to manually
          edit the ``.gitmodules`` file to add ``branch = .`` and then
          commit it. Something like::

            <edit the .gitmodules file>
            git add .gitmodules
            git commit --amend

When you're done you should have a git commit something like::

  $ git show
  commit 7943ce2cb41cd9d36ce93ee9003510ce3edd7fa9
  Author: Daniel Farrell <dfarrell@redhat.com>
  Date:   Fri Dec 23 14:45:44 2016 -0500

      Add Int/Pack to git submodules for RTD generation

      Change-Id: I64cd36ca044b8303cb7fc465b2d91470819a9fe6
      Signed-off-by: Daniel Farrell <dfarrell@redhat.com>

  diff --git a/.gitmodules b/.gitmodules
  index 91201bf6..b56e11c8 100644
  --- a/.gitmodules
  +++ b/.gitmodules
  @@ -38,3 +38,7 @@
          path = docs/submodules/ovsdb
          url = ../ovsdb
          branch = .
  +[submodule "docs/submodules/integration/packaging"]
  +       path = docs/submodules/integration/packaging
  +       url = ../integration/packaging
  +       branch = master
  diff --git a/docs/submodules/integration/packaging b/docs/submodules/integration/packaging
  new file mode 160000
  index 00000000..fd5a8185
  --- /dev/null
  +++ b/docs/submodules/integration/packaging
  @@ -0,0 +1 @@
  +Subproject commit fd5a81853e71d45945471d0f91bbdac1a1444386

As usual, you can push it to Gerrit with ``git review``.

.. important:: It's critical that the Gerrit patch be merged before the
               git commit hash of the submodule changes. Otherwise,
               Gerrit won't be able to automatically keep it up-to-date
               for you.

Documentation Layout and Style
------------------------------

As mentioned previously we try to follow the python documentation style
guide which defines a few types of sections::

    # with overline, for parts
    * with overline, for chapters
    =, for sections
    -, for subsections
    ^, for subsubsections
    ", for paragraphs

We try to follow the following structure based on that recommendation::

    docs/index.rst                 -> entry point
    docs/____-guide/index.rst      -> part
    docs/____-guide/<chapter>.rst  -> chapter

In the ____-guide/index.rst we use the # with overline at the very top
of the file to determine that it is a part and then within each chapter
file we start the document with a section using * with overline to
denote that it's the chapter heading and then everything in the rest of
the chapter should use::

    =, for sections
    -, for subsections
    ^, for subsubsections
    ", for paragraphs

Referencing Sections
^^^^^^^^^^^^^^^^^^^^

It's pretty common to want to reference another location in the
OpenDaylight documentation and it's pretty easy to do with
reStructuredText. This is a quick primer, more information is in the
`Sphinx section on Cross-referencing arbitrary locations
<http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.

Within a single document, you can reference another section simply by::

   This is a reference to `The title of a section`_

Assuming that somewhere else in the same file there a is a section
title something like::

   The title of a section
   ^^^^^^^^^^^^^^^^^^^^^^

It's typically better to use ``:ref:`` syntax and labels to provide
links as they work across files and are resilient to sections being
renamed. First, you need to create a label something like::

   .. _a-label:

   The title of a section
   ^^^^^^^^^^^^^^^^^^^^^^

.. note:: The underscore (_) before the label is required.

Then you can reference the section anywhere by simply doing::

    This is a reference to :ref:`a-label`

or::

    This is a reference to :ref:`a section I really liked <a-label>`

.. note:: When using ``:ref:``-style links, you don't need a trailing
          underscore (_).

Because the labels have to be unique, it usually makes sense to prefix
the labels with the project name to help share the label space, e.g.,
``sfc-user-guide`` instead of just ``user-guide``.


.. _docs-rst-troubleshooting:

Troubleshooting
---------------

Nested formatting doesn't work
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

As stated in the reStructuredText_ guide, inline markup for bold,
italic, and fixed-width can't be nested. Further, it can't be mixed
with hyperlinks, so you can't have bold text link somewhere.

This is tracked in a `Docutils FAQ question
<http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible>`_,
but there is no clear current plan to fix this.

Make sure you've cloned submodules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you see an error like this::

   ./build-integration-robot-libdoc.sh: line 6: cd: submodules/integration/test/csit/libraries: No such file or directory
   Resource file '*.robot' does not exist.

It means that you haven't pulled down the git submodule for the
integration/test project. The fastest way to do that is::

   git submodule update --init

In some cases, you might wind up with submodules which are somehow
out-of-sync and in that case, the easiest way to fix it is delete the
submodules directory and then re-clone the submodules::

   rm -rf docs/submodules/
   git submodule update --init

.. warning:: This will delete any local changes or information you made
             in the submodules. This should only be the case if you
             manually edited files in that directory.

Clear your tox directory and try again
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Sometimes, tox will not detect when your ``requirements.txt`` file has
changed and so will try to run things without the correct dependencies.
This usually manifests as ``No module named X`` errors or
an ``ExtensionError`` and can be fixed by deleting the ``.tox``
directory and building again::

   rm -rf .tox
   tox

Builds on Read the Docs
^^^^^^^^^^^^^^^^^^^^^^^

It appears as though the Read the Docs builds don't automatically clear
the file structure between builds and clones. The result is that you
may have to clean up the state of old runs of the build script.

As an example, this patch:
https://git.opendaylight.org/gerrit/41679

Finally fixed the fact that our builds for failing because they were
taking too long by removing directories of generated javadoc that were
present from previous runs.

Weird Errors from Coala
^^^^^^^^^^^^^^^^^^^^^^^

As pat of running ``tox``, two environments run: ``coala`` which does a variety
of reStructuredText_ (and other) linting, and ``docs``, which runs Sphinx_ to
build HTML and PDF documentation. You can run them independently by doing
``tox -ecoala`` or ``tox -edocs``.

The ``coala`` linter for reStructuredText isn't always the most helpful in
explaining why it failed. So, here are some common ones. There should also be
Jenkins Failure Cause Management rules that will highlight these for you.

Git Commit Message Errors
"""""""""""""""""""""""""

Coala will check git commit messages for a variety of things including

* Shortlog (1st line of commit message) is less than 50 characters
* Shortlog (1st line of commit message) is in the imperative mood, e.g., "Add
  foo unit test" is good, but "Adding foo unit test is bad""
* Body (all lines but 1st line of commit message) are less than 72 characters.
  Some exceptions seem to exist, e.g., for long URLs.

Some examples of those being logged are:

::
   Project wide:
   |    | [NORMAL] GitCommitBear:
   |    | Shortlog of HEAD commit isn't in imperative mood! Bad words are 'Adding'

::
   Project wide:
   |    | [NORMAL] GitCommitBear:
   |    | Body of HEAD commit contains too long lines. Commit body lines should not exceed 72 characters.

Error in "code-block" directive
"""""""""""""""""""""""""""""""

If you see an error like this:

::
   docs/gerrit.rst
   |  89| ···..·code-block::·bash
   |    | [MAJOR] RSTcheckBear:
   |    | (ERROR/3) Error in "code-block" directive:

It seems to mean that the relevant code-block does is not valid for the
language specified, in this case bash. Note that if you specify no language, it
seems as though it assumes the language is python. If you want the code-block
to not be an any particular language, instead use the ``::`` directive. For
example:

::
   ::
      This is a code block
      that will not be parsed
      in any particluar langauge

Project Documentation Requirements
==================================

Submitting Documentation Outlines (M3)
--------------------------------------

#. Determine the features your project will have and which ones will be
   ''user-facing''.

   * In general, a feature is user-facing if it creates functionality that a
     user would direction interact with.
   * For example, ``odl-openflowplugin-flow-services-ui`` is likely
     user-facing since it installs user-facing OpenFlow features, while
     ``odl-openflowplugin-flow-services`` is not because it provides only
     developer-facing features.

#. Determine pieces of documentation you need provide based on the features
   your project will have and which ones will be user-facing.

   * The kinds of required documentation can be found below in the
     :ref:`requirements-for-projects` section.
   * Note that you might need to create multiple different documents for the
     same kind of documentation. For example, the controller project will
     likely want to have a developer section for the config subsystem as well
     as a for the MD-SAL.

#. Clone the docs repo: ``git clone https://git.opendaylight.org/gerrit/docs``
#. For each piece of documentation find the corresponding template in the docs repo.

   * For user documentation: ``docs.git/docs/templates/template-user-guide.rst``
   * For developer documentation: ``ddocs/templates/template-developer-guide.rst``
   * For installation documentation (if any): ``docs/templates/template-install-guide.rst``

   .. note:: You can find the rendered templates here:

             .. toctree::
                :maxdepth: 1

                templates/template-user-guide
                templates/template-developer-guide
                templates/template-install-guide.rst


#. Copy the template into the appropriate directory for your project.

   * For user documentation: ``docs.git/docs/user-guide/${feature-name}-user-guide.rst``
   * For developer documentation: ``docs.git/docs/developer-guide/${feature-name}-developer-guide.rst``
   * For installation documentation (if any): ``docs.git/docs/getting-started-guide/project-specific-guides/${project-name}.rst``

   .. note:: These naming conventions aren't set in stone, but do help. If you
             think there's a better name, use it and we'll give feedback on the
             gerrit patch.

#. Edit the template to fill in the outline of what you will provide using the
   suggestions in the template. If you feel like a section isn't needed, feel
   free to omit it.

#. Link the template into the appropriate core rst file

   * For user documentation: ``docs.git/docs/user-guide/index.rst``
   * For developer documentation: ``docs.git/docs/developer-guide/index.rst``
   * For installation documentation (if any): ``docs.git/docs/getting-started-guide/project-specific-guides/index.rst``
   * In each file, it should be pretty clear what line you need to add. In
     general if you have an rst file ``project-name.rst``, you include it by
     adding a new line ``project-name`` without the ``.rst`` at the end.

#. Make sure the documentation project still builds.

   * Run ``tox`` from the root of the cloned docs repo.

     * After that, you should be able to find the HTML version of the
       docs at ``docs.git/docs/_build/html/index.html``.
     * See :ref:`docs-rst` for more details about building the docs.

   * The :ref:`reStructuredText Troubleshooting <docs-rst-troubleshooting>`
     section provides common errors and solutions.
   * If you still have problems e-mail the documentation group at
     documentation@lists.opendaylight.org

#. Commit and submit the patch

   #. Commit using:

      .. code-block:: bash

         git add --all && git commit -sm "Documentation outline for ${project-shortname}"

   #. Submit using:

      .. code-block:: bash

         git review

      See the `Git-review Workflow <https://wiki.opendaylight.org/view/Git-review_Workflow>`_
      page if you don't have git-review installed.

#. Wait for the patch to be merged or to get feedback

   * If you get feedback, make the requested changes and resubmit the patch.
   * When you resubmit the patch, it's helpful if you also post a +0 reply to
     the gerrit saying what patch set you just submitted and what you fixed in
     the patch set.
   * 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.

Expected Output From Documentation Project
------------------------------------------

The expected output is (at least) 3 PDFs and equivalent web-based documentation:

* User/Operator Guide
* Developer Guide
* Installation Guide

These guides will consist of "front matter" produced by the documentation group
and the per-project/per-feature documentation provided by the projects. Note
that this is intended to be who is responsible for the documentation and should
not be interpreted as preventing people not normally in the documentation group
from helping with "front matter" nor preventing people from the documentation
group from helping with per-project/per-feature documentation.

Boron Project Documentation Requirements
----------------------------------------

.. _kinds-of-docs:

Kinds of Documentation
^^^^^^^^^^^^^^^^^^^^^^

These are the expected kinds of documentation and target audiences for each kind.

* **User/Operator:** for people looking to use the feature w/o writing code

  * Should include an overview of the project/feature
  * Should include description of availbe configuration options and what they do

* **Developer:** for people looking to use the feature in code w/o modifying it

  * Should include API documentation, e.g., enunciate for REST, Javadoc for
    Java, ??? for RESTCONF/models

* **Contributor:** for people looking to extend or modify the feature's source
  code

  .. note:

     should be documented on the wiki not in reStructuredText

* **Installation:** for people looking for instructions to install the feature
  after they have downloaded the ODL release

  .. note:

     audience is the same as User/Operator docs

  * For most projects, this will be just a list of top-level features and
    options

    * As an example, l2switch-switch as the top-level feature with the -rest
      and -ui options
    * We'd also like them to note if the options should be checkboxes (i.e.,
      they can each be turned on/off independently) or a drop down (i.e., at
      most one can be selected)
    * What other top-level features in the release are incompatible with each
      feature
    * This will likely be presented as a table in the documentation and the
      data will likely also be consumed by automated installers/configurators/downloaders

  * For some projects, there is extra installation instructions (for external
    components) and/or configuration

    * In that case, there will be a (sub)section in the documentation
      describing this process.

* **HowTo/Tutorial:** walk throughs and examples that are not general-purpose
  documentation

  * Generally, these should be done as a (sub)section of either user/operator
    or developer documentation.
  * If they are especially long or complex, they may belong on their own

* **Release Notes:**

  * Release notes are required as part of each project's release review. They
    must also be translated into reStructuredText for inclusion in the formal
    documentation.

.. _requirements-for-projects:

Requirements for projects
^^^^^^^^^^^^^^^^^^^^^^^^^

Projects MUST do the following

* Provide reStructuredText documentation including

  * Developer documentation for every feature

    * Most projects will want to logically nest the documentation for
      individual features under a single project-wide chapter or section
    * This can be provided as a single .rst file or multiple .rst files if
      the features fall into different groups
    * This should start with ~300 word overview of the project and include
      references to any automatically-generated API documentation as well as
      more general developer information (see
      :ref:`kinds-of-docs`).

  * User/Operator documentation for every every user-facing feature (if any)

    * ''Note: This should be per-feature, not per-project. User's shouldn't have to know which project a feature came from.''
    * Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences
    * This can be provided as a single .rst file or multiple .rst files if the features fall into different groups

  * Installation documentation

    * Most projects will simply provide a list of user-facing features and
      options. See :ref:`kinds-of-docs` above.

  * Release Notes (both on the wiki and reStructuredText) as part of the release review.

* This documentation will be contributed to the docs repo (or possibly imported from the project's own repo with tooling that is under development)

  * Projects MAY be ENCOURGAGED to instead provide this from their own repository if the tooling is developed
  * Projects choosing to meet the requirement this way MUST provide a patch to docs repo to import the project's documentation

* Projects MUST cooperate with the documentation group on edits and enhancements to documentation

  * 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.

Timeline for Deliverables from Projects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* **M3:** Documentation Started

  * Identified the kinds of documentation that will be provided and for what
    features

    * Release Notes are not required until release reviews at **RC2**

  * Created the appropriate .rst files in the docs repository (or their own
    repository if the tooling is available)
  * Have an outline for the expected documentation in those .rst files
    including the relevant (sub)sections and a sentence or two explaining what
    will go there

    * Obviusly, providing actual documentation in the (sub)sections is
      encouraged and meets this requirement

  * Milestone readout should include

    #. the list of kinds of documentation
    #. the list of corresponding .rst files and their location, e.g., repo and
       path
    #. the list of commits creating those .rst files
    #. the current word counts of those .rst files

* **M4:** Documentation Continues

  * The readout at M4 should include the word counts of all .rst files with
    links to commits
  * The goal is to have draft documentation complete so that the documentation
    group can comment on it.

* **M5:** Documentation Complete

  * All (sub)sections in all .rst files have complete, readable, usable content.
  * Ideally, there should have been some interaction with the documentation
    group about any suggested edits and enhancements

* **RC2:** Release notes

  * Projects must provide release notes as .rst pushed to integration (or
    locally in the project's repository if the tooling is developed)


.. _Sphinx: http://www.sphinx-doc.org/en/stable/
.. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html
.. _Documentation Group: https://wiki.opendaylight.org/view/Documentation/
.. _RelEng/Builder: https://wiki.opendaylight.org/view/RelEng/Builder
.. _Pandoc: http://pandoc.org/