Merge "Start Silicon platform upgrade guide"
[docs.git] / docs / documentation.rst
index d06930b2e95b336aad80a9566236712f0bb5d71e..57e95b922dae273f4e2079dcb115632d186921f7 100644 (file)
@@ -5,13 +5,11 @@ Documentation Guide
 ###################
 
 This guide provides details on how to contribute to the OpenDaylight
 ###################
 
 This guide provides details on how to contribute to the OpenDaylight
-documentation. OpenDaylight currently uses a mix of AsciiDoc_ and
-reStructuredText_ for documentation, although the `Documentation
-Group`_ is generally trying to move toward using reStructuredText_ 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.
+documentation. OpenDaylight currently uses reStructuredText_ for
+documentation and Sphinx_ to build it. These documentation tools are widely used
+in open source communities to produce both HTML and PDF documentation and can
+be easily versioned alongside the code. reStructuredText also offers similar
+syntax to Markdown, which is familiar to many developers.
 
 .. contents:: Contents
    :depth: 2
 
 .. contents:: Contents
    :depth: 2
@@ -22,31 +20,33 @@ Style Guide
 
 This section serves two purposes:
 
 
 This section serves two purposes:
 
-#. A guide for those writing documentation to follow.
+#. A guide for those writing documentation.
 #. A guide for those reviewing documentation.
 
 #. 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.
+.. note:: When reviewing content, assuming that the content is usable, the
+          documentation team is biased toward merging the content rather than
+          blocking it due to relatively minor editorial issues.
 
 Formatting Preferences
 ----------------------
 
 
 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:
+In general, when reviewing content, the documentation team ensures that it
+is comprehensible but tries not to be overly pedantic. Along those lines,
+while it is preferred that the following formatting preferences are followed,
+they are generally not an exclusive reason to give a "-1" reply to a patch in
+Gerrit:
 
 * No trailing whitespace
 
 * No trailing whitespace
-* Line wrapping at something reasonable, i.e., 72–100 characters
+* Line wrapping at something reasonable, that is, 72–100 characters
 
 Key terms
 ---------
 
 * Functionality: something useful a project provides abstractly
 * Feature: a Karaf feature that somebody could install
 
 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
+* Project: a project within OpenDaylight; projects ship features to
   provide functionality
   provide functionality
-* OpenDaylight: this refers to the software we release, use this in
+* OpenDaylight: this refers to the software we release; use this in
   place of OpenDaylight controller, the OpenDaylight controller, not
   ODL, not ODC
 
   place of OpenDaylight controller, the OpenDaylight controller, not
   ODL, not ODC
 
@@ -58,7 +58,7 @@ 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
 
 * 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
+  per the getting started guide and start with ``feature:install
   <something>``
 * Avoid statements which are true about part of OpenDaylight, but not
   generally true.
   <something>``
 * Avoid statements which are true about part of OpenDaylight, but not
   generally true.
@@ -74,20 +74,22 @@ Common writing style mistakes
 Grammar Preferences
 ^^^^^^^^^^^^^^^^^^^
 
 Grammar Preferences
 ^^^^^^^^^^^^^^^^^^^
 
-* Avoid contractions: use cannot instead of can't, it is instead of
-  it's, and the like.
+* Avoid contractions: Use "cannot" instead of "can't", "it is" instead of
+  "it's", and so on.
 
 
-Things to get right with spacing and capitalization
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Word Choice
+^^^^^^^^^^^^
 
 
-*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.*
+.. note:: The following word choice guidelines apply when using these terms in
+          text. If these terms are used as part of a URL, class name, or
+          any instance where modifying the case would create issues, use the
+          exact capitalization and spacing associated with the URL or class
+          name.
 
 * ACL: not Acl or acl
 * API: not api
 * ARP: not Arp or arp
 
 * 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
+* datastore: not data store, Data Store, or DataStore (unless it is a
   class/object name)
 * IPsec, not IPSEC or ipsec
 * IPv4 or IPv6: not Ipv4, Ipv6, ipv4, ipv6, IPV4, or IPV6
   class/object name)
 * IPsec, not IPSEC or ipsec
 * IPv4 or IPv6: not Ipv4, Ipv6, ipv4, ipv6, IPV4, or IPV6
@@ -96,12 +98,12 @@ capitalization and spacing.*
 * NETCONF: not Netconf or netconf
 * Neutron: not neutron
 * OSGi: not osgi or OSGI
 * 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.
+* Open vSwitch: not OpenvSwitch, OpenVSwitch, or Open V Switch.
+* OpenDaylight: not Opendaylight, Open Daylight, or OpenDayLight.
 
 
-  * also avoid abbreviations like ODL and ODC
+  .. note:: Also, avoid Opendaylight abbreviations like ODL and ODC.
 
 
-* OpenFlow: not Openflow, Open Flow, openflow, etc.
+* OpenFlow: not Openflow, Open Flow, or openflow.
 * OpenStack: not Open Stack or Openstack
 * QoS: not Qos, QOS, or qos
 * RESTCONF: not Restconf or restconf
 * OpenStack: not Open Stack or Openstack
 * QoS: not Qos, QOS, or qos
 * RESTCONF: not Restconf or restconf
@@ -110,24 +112,27 @@ capitalization and spacing.*
 * VM: not Vm or vm
 * YANG: not Yang or yang
 
 * VM: not Vm or vm
 * YANG: not Yang or yang
 
+.. _docs-rst:
+
 reStructuredText-based Documentation
 ====================================
 
 reStructuredText-based Documentation
 ====================================
 
-When using reStructuredText, we try to follow the python documentation
-style guide. See: https://docs.python.org/devguide/documenting.html
+When using reStructuredText, follow the Python documentation
+style guidelines. See: https://devguide.python.org/documenting/
 
 
-The best reference for reStrucutedText syntax seems to be the Sphinx
+One of the best references for reStrucutedText syntax is the Sphinx
 Primer on reStructuredText_.
 
 Primer on reStructuredText_.
 
-To build and review the reStructuredText documentation locally you must
-have installed locally:
+To build and review the reStructuredText documentation locally, you must
+have the following packages installed locally:
 
 * python
 * python-tox
 
 
 * python
 * python-tox
 
-Which both should be available in most distribution's package managers.
+.. note:: Both packages should be available in most distribution package
+          managers.
 
 
-Then simply run tox and open the html produced via your favorite web
+Then simply run ``tox`` and open the HTML produced by using your favorite web
 browser as follows:
 
 .. code-block:: bash
 browser as follows:
 
 .. code-block:: bash
@@ -135,12 +140,9 @@ browser as follows:
    git clone https://git.opendaylight.org/gerrit/docs
    cd docs
    git submodule update --init
    git clone https://git.opendaylight.org/gerrit/docs
    cd docs
    git submodule update --init
-   tox -edocs
+   tox
    firefox docs/_build/html/index.html
 
    firefox docs/_build/html/index.html
 
-.. note:: Make sure to run `tox -edocs` and not just `tox`. See `Make
-          sure you run tox -edocs`_
-
 Directory Structure
 -------------------
 
 Directory Structure
 -------------------
 
@@ -148,11 +150,12 @@ The directory structure for the reStructuredText documentation is
 rooted in the ``docs`` directory inside the ``docs`` ``git``
 repository.
 
 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.
+.. note:: There are guides hosted directly in the ``docs`` ``git``
+          repository and there are guides hosted in remote ``git`` repositories.
+          Documentation hosted in remote ``git`` repositories are generally
+          provided for project-specific information.
 
 
-For example here is the directory layout on June, 28th 2016::
+For example, here is the directory layout on June, 28th 2016::
 
    $ tree -L 2
    .
 
    $ tree -L 2
    .
@@ -187,8 +190,8 @@ directories correspond to two guides hosted in the ``docs`` repository,
 while the ``submodules/releng/builder`` directory houses documentation
 for the `RelEng/Builder`_ project.
 
 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::
+Each guide includes an ``index.rst`` file, which uses a ``toctree``
+directive that includes the other files associated with the guide. For example::
 
    .. toctree::
       :maxdepth: 1
 
    .. toctree::
       :maxdepth: 1
@@ -197,17 +200,78 @@ includes other files using a ``toctree`` directive. For example::
       opendaylight-with-openstack/index
       submodules/releng/builder/docs/index
 
       opendaylight-with-openstack/index
       submodules/releng/builder/docs/index
 
-This creates a table of contents on that page where each heading of the
+This example 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.
 
 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.
+.. note:: When including ``.rst`` files using the ``toctree`` directive, omit
+          the ``.rst`` file extension 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 by 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 tracks whatever branch
+          of the documentation project you happen to be on.
+
+          Unfortunately, ``-b .`` does not work, so you have to manually
+          edit the ``.gitmodules`` file to add ``branch = .`` and then
+          commit it. For example::
+
+            <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 is critical that the Gerrit patch be merged before the
+               git commit hash of the submodule changes. Otherwise,
+               Gerrit is not able to automatically keep it up-to-date
+               for you.
 
 Documentation Layout and Style
 ------------------------------
 
 
 Documentation Layout and Style
 ------------------------------
 
-As mentioned previously we try to follow the python documentation style
-guide which defines a few types of sections::
+As mentioned previously, OpenDaylight aims to follow the Python documentation
+style guidelines, which defines a few types of sections::
 
     # with overline, for parts
     * with overline, for chapters
 
     # with overline, for parts
     * with overline, for chapters
@@ -216,16 +280,17 @@ guide which defines a few types of sections::
     ^, for subsubsections
     ", for paragraphs
 
     ^, for subsubsections
     ", for paragraphs
 
-We try to follow the following structure based on that recommendation::
+OpenDaylight documentation is organized around the following structure based on
+that recommendation::
 
     docs/index.rst                 -> entry point
     docs/____-guide/index.rst      -> part
     docs/____-guide/<chapter>.rst  -> chapter
 
 
     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
+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
 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
+file we start the document with a section using ``*`` with overline to
+denote that it is the chapter heading and then everything in the rest of
 the chapter should use::
 
     =, for sections
 the chapter should use::
 
     =, for sections
@@ -236,23 +301,22 @@ the chapter should use::
 Referencing Sections
 ^^^^^^^^^^^^^^^^^^^^
 
 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>`_.
+This section provides a quick primer for creating references
+in OpenDaylight documentation. For more information, refer to
+`Cross-referencing documents
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_.
 
 Within a single document, you can reference another section simply by::
 
    This is a reference to `The title of a section`_
 
 
 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
+Assuming that somewhere else in the same file, there a is a section
 title something like::
 
    The title of a section
    ^^^^^^^^^^^^^^^^^^^^^^
 
 title something like::
 
    The title of a section
    ^^^^^^^^^^^^^^^^^^^^^^
 
-It's typically better to use ``:ref:`` syntax and labels to provide
+It is 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::
 
 links as they work across files and are resilient to sections being
 renamed. First, you need to create a label something like::
 
@@ -271,283 +335,225 @@ or::
 
     This is a reference to :ref:`a section I really liked <a-label>`
 
 
     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 (_).
 
 .. 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``.
+Because the labels have to be unique, a best practice is to prefix
+the labels with the project name to help share the label space; for example,
+use ``sfc-user-guide`` instead of just ``user-guide``.
+
+
+.. _docs-rst-troubleshooting:
 
 Troubleshooting
 ---------------
 
 
 Troubleshooting
 ---------------
 
-Nested formatting doesn't work
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Nested formatting does not work
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 As stated in the reStructuredText_ guide, inline markup for bold,
 
 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.
+italic, and fixed-width font cannot be nested. Furthermore, inline markup cannot
+be mixed with hyperlinks, so you cannot have a link with bold text.
 
 This is tracked in a `Docutils FAQ question
 
 This is tracked in a `Docutils FAQ question
-<http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible>`_,
+<https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible>`_,
 but there is no clear current plan to fix this.
 
 but there is no clear current plan to fix this.
 
-Make sure you've cloned submodules
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Make sure you have 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.
 
 
 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
+It means that you have not 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
 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
+out-of-sync. In that case, the easiest way to fix them is to delete the
 submodules directory and then re-clone the submodules::
 
    rm -rf docs/submodules/
    git submodule update --init
 
 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
+.. warning:: These steps delete any local changes or information you made
+             in the submodules, which would only occur if you
              manually edited files in that directory.
 
              manually edited files in that directory.
 
-Make sure you run tox -edocs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you see an error like::
-
-   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)
-   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)
-
-It usually means you ran `tox` and not `tox -edocs`, which will result
-in running jobs inside submodules which aren't supported by the
-environment defined by the `requirements.txt` file in the documentation
-tox setup. Just run tox -edocs and it should be fine.
-
 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.
 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
+This issue 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
 an ``ExtensionError`` and can be fixed by deleting the ``.tox``
 directory and building again::
 
    rm -rf .tox
-   tox -edocs
+   tox
 
 Builds on Read the Docs
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 
 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.
-
-AsciiDoc-based Documentation
-============================
-
-Information on the AsciiDoc tools and build system can be found here:
-https://wiki.opendaylight.org/view/Documentation/Tools
-
-Directory Structure
--------------------
-
-The AsciiDoc documentation is all located in the ``manuals`` directory
-of the ``docs`` ``git`` repository. An example of the directory
-structure on June 28th, 2016 can be seen here::
-
-   $ tree -L 4
-   .
-   ├── common
-   │   └── app_support.xml
-   ├── developer-guide
-   │   ├── pom.xml
-   │   └── src
-   │       └── main
-   │           ├── asciidoc
-   │           └── resources
-   ├── getting-started-guide
-   │   ├── pom.xml
-   │   └── src
-   │       └── main
-   │           ├── asciidoc
-   │           └── resources
-   ├── howto-openstack
-   │   ├── pom.xml
-   │   └── src
-   │       └── main
-   │           ├── asciidoc
-   │           └── resources
-   ├── pom.xml
-   ├── readme
-   │   ├── pom.xml
-   │   └── src
-   │       └── main
-   │           └── asciidoc
-   └── user-guide
-       ├── pom.xml
-       └── src
-           └── main
-               ├── asciidoc
-               └── resources
-
-Each of the top-level directories under ``manuals`` is a whole guide by
-itself and it contains a ``pom.xml`` file saying how to build it, a
-``src/main/asciidoc`` directory with AsciiDoc source files and a
-``src/main/resources`` directory containing images.
-
-Troubleshooting
----------------
-
-See `AsciiDoc Tips`_ on the wiki for more information.
-
-Common AsciiDoc mistakes
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-See also `AsciiDoc Tips`_.
-
-* Lists that get formatted incorrectly because of no blank line above
-  the list.
-* Numbered lists that are formatted incorrectly and every bullet winds
-  up being 1
+Read the Docs builds do not 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.
 
 
-Migration from AsciiDoc to ReStructuredText
-===========================================
+As an example, refer to the following patch:
+https://git.opendaylight.org/gerrit/c/docs/+/41679/
 
 
-Automatically
--------------
+This patch fixed the issue that caused builds to fail because they were
+taking too long removing directories associated with generated
+javadoc files that were present from previous runs.
 
 
-In theory, Pandoc_ can convert from DocBook to reStructuredText and we
-produce DocBook as part of our build chain from AsciiDoctor. In
-practice, for modest-sized migrations doing things by hand works fairly
-well.
+Errors from Coala
+^^^^^^^^^^^^^^^^^^
 
 
-By Hand
--------
+As part 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``.
 
 
-Converting from AsciiDoc to reStructuredText is usually pretty
-straightforward and involves looking up the basic syntax for what you
-want to do by looking it up in the reStructuredText_ guide.
+The ``coala`` linter for reStructuredText is not 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.
 
 
-The differences are usually minor and fast to change.
+Git Commit Message Errors
+"""""""""""""""""""""""""
 
 
-Also, because of how fast Sphinx builds, and how fast it is to refresh
-the HTML documentation rapid iteration is very easy.
+Coala checks that git commit messages adhere to the following rules:
 
 
-Bold/Italics/Verbatim Formatting
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* Shortlog (1st line of commit message) is less than 50 characters
+* Shortlog (1st line of commit message) is in the imperative mood. For example,
+  "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, such as for long URLs.
 
 
-This is mostly minor syntax issues. In AsciiDoc you do inline
-formatting something like this::
+Some examples of those being logged are:
 
 
-   *bold* _italic_ +verbatim+ `verbatim`
+::
+   Project wide:
+   |    | [NORMAL] GitCommitBear:
+   |    | Shortlog of HEAD commit isn't in imperative mood! Bad words are 'Adding'
 
 
-In reStructuredText, things are slightly different::
+::
+   Project wide:
+   |    | [NORMAL] GitCommitBear:
+   |    | Body of HEAD commit contains too long lines. Commit body lines should not exceed 72 characters.
 
 
-   **bold** *italic* ``verbatim``
+Error in "code-block" directive
+"""""""""""""""""""""""""""""""
 
 
-Images
-^^^^^^
+If you see an error like this:
 
 
-Image formats change from something like::
+::
+   docs/gerrit.rst
+   |  89| ···..·code-block::·bash
+   |    | [MAJOR] RSTcheckBear:
+   |    | (ERROR/3) Error in "code-block" directive:
 
 
-   .OpenStack Architecture
-   image::vtn/OpenStackDeveloperGuide.png["OpenStack Architecture",width=500]
+It means that the relevant code-block is not valid for the
+language specified, in this case ``bash``.
 
 
-To something like::
-
-   .. figure:: images/dlux-default.png
-
-A helpful regular expression for automating the replacements is
-something like::
-
-   search: ^( *)\.(.+)\n +image::(.+)\[(.+),width=(\d+)\]
-   replace: $1.. figure:: images/dlux/$3\n$1   :width: $5\n\n$1   $2
+.. note:: If you do not specify a language, the default 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
 ==================================
 
 
 Project Documentation Requirements
 ==================================
 
-Submitting Documentation Outlines (M3)
+Submitting Documentation Outlines (M2)
 --------------------------------------
 
 #. 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
 --------------------------------------
 
 #. 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.
+     user would directly 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.
 
    * 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.
+#. Determine pieces of documentation that you need to 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.
 
    * 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.
+
+   .. note:: You might need to create multiple 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 for the MD-SAL.
 
 #. Clone the docs repo: ``git clone https://git.opendaylight.org/gerrit/docs``
 
 #. 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 each piece of documentation find the corresponding template in the docs
+   repo.
 
 
-   * For user documentation: ``docs.git/manuals/readme/src/main/asciidoc/template_user_guide.adoc``
-   * For developer documentation: ``docs.git/manuals/readme/src/main/asciidoc/template_developer_guide.adoc``
-   * For installation documentation (if any): ``docs.git/manuals/readme/src/main/asciidoc/template_installation_guide.adoc``
+   * 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``
 
 
-#. Copy the template into the appropriate directory for your project.
+   .. note:: You can find the rendered templates here:
 
 
-   * For user documentation: ``docs.git/manuals/user-guide/src/main/asciidoc/${project-shortname}/${feature-name}-user.adoc``
-   * For developer documentation: ``docs.git/manuals/developer-guide/src/main/asciidoc/${project-shortname}/${feature-name}-dev.adoc``
-   * For installation documentation (if any): ``docs.git/manuals/install-guide/src/main/asciidoc/${project-shortname}/${feature-name}-install.adoc``
+             .. toctree::
+                :maxdepth: 1
 
 
-#. Edit the template to fill in the outline of what you will provide using the
-   suggestions in the template.
+                templates/template-user-guide
+                templates/template-developer-guide
+                templates/template-install-guide.rst
 
 
-   * DO NOT leave any sections blank as blank sections will cause build errors.
 
 
-#. Link the template into the appropriate core adoc file
+#. Copy the template into the appropriate directory for your project.
 
 
-   * For user documentation: ``docs.git/manuals/user-guide/src/main/asciidoc/bk-user-guide.adoc``
-   * For developer documentation: ``docs.git/manuals/developer-guide/src/main/asciidoc/bk-developers-guide.adoc``
-   * For installation documentation (if any): ``docs.git/manuals/install-guide/src/main/asciidoc/bk-install-guide.adoc``
-   * Add a line like:
+   * 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``
 
 
-     .. code-block:: none
+   .. note:: These naming conventions are not set in stone, but are used to
+             maintain a consistent document taxonomy. If these conventions
+             are not appropriate or do not make sense for a document
+             in development, use the convention that you think is more
+             appropriate and the documentation team will review it and give
+             feedback on the gerrit patch.
 
 
-        include::${project-shortname}/${feature-name}-user.adoc[]
+#. 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 is not needed, feel
+   free to omit it.
 
 
-   * Make sure there is a blank line between your include statement and any others as this prevents sections from running into each other.
+#. 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.
 
 
 #. Make sure the documentation project still builds.
 
-   * Run ``mvn clean install`` from the root of the cloned docs repo.
+   * Run ``tox`` from the root of the cloned docs repo.
 
 
-     * After that, you should be able to find the PDF and HTML version of the
-       docs. Use ``find . -name *.pdf`` to find the PDF and the HTML is
-       always at ``target/docbkx/webhelp/${manual-name}/index.html``.
+     * 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 `AsciiDoc tips <https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Tools:AsciiDoc_Tips>`_
-     page provide common errors and solutions.
+   * 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
 
    * If you still have problems e-mail the documentation group at
      documentation@lists.opendaylight.org
 
-#. Commit and submit the patch
+#. Commit and submit the patch.
 
    #. Commit using:
 
 
    #. Commit using:
 
@@ -561,19 +567,15 @@ Submitting Documentation Outlines (M3)
 
          git review
 
 
          git review
 
-      See the `Git-review Workflow <https://wiki.opendaylight.org/view/Git-review_Workflow>`_
+      See the `Git-review Workflow <https://wiki-archive.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.
       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.
+   * When you resubmit the patch, it is helpful if you also post a "+0" reply to
+     the patch in Gerrit, stating what patch set you just submitted and what you
+     fixed in the patch set.
 
 Expected Output From Documentation Project
 ------------------------------------------
 
 Expected Output From Documentation Project
 ------------------------------------------
@@ -585,58 +587,60 @@ The expected output is (at least) 3 PDFs and equivalent web-based documentation:
 * Installation Guide
 
 These guides will consist of "front matter" produced by the documentation group
 * 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.
+and the per-project/per-feature documentation provided by the projects.
+
+.. note:: This requirement is intended for the person 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
-----------------------------------------
+Project Documentation Requirements
+----------------------------------
 
 .. _kinds-of-docs:
 
 
 .. _kinds-of-docs:
 
-Kinds of Documentation
-^^^^^^^^^^^^^^^^^^^^^^
+Content Types
+^^^^^^^^^^^^^
 
 
-These are the expected kinds of documentation and target audiences for each kind.
+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
+* **User/Operator:** for people looking to use the feature without writing code
 
   * Should include an overview of the project/feature
 
   * Should include an overview of the project/feature
-  * Should include description of availbe configuration options and what they do
+  * Should include description of availble configuration options and what they
+    do
 
 
-* **Developer:** for people looking to use the feature in code w/o modifying it
+* **Developer:** for people looking to use the feature in code without modifying
+  it
 
 
-  * Should include API documentation, e.g., enunciate for REST, Javadoc for
+  * Should include API documentation, such as, enunciate for REST, Javadoc for
     Java, ??? for RESTCONF/models
 
 * **Contributor:** for people looking to extend or modify the feature's source
   code
 
     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 asciidoc
+  .. note:: You can find this information on the wiki.
 
 * **Installation:** for people looking for instructions to install the feature
   after they have downloaded the ODL release
 
 
 * **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
+  .. note:: The audience for this content 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
 
   * 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
+    * Features should also note if the options should be checkboxes (that is,
+      they can each be turned on/off independently) or a drop down (that is, 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
       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
+      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
 
   * For some projects, there is extra installation instructions (for external
     components) and/or configuration
@@ -654,7 +658,7 @@ These are the expected kinds of documentation and target audiences for each kind
 * **Release Notes:**
 
   * Release notes are required as part of each project's release review. They
 * **Release Notes:**
 
   * Release notes are required as part of each project's release review. They
-    must also be translated into AsciiDoc for inclusion in the formal
+    must also be translated into reStructuredText for inclusion in the formal
     documentation.
 
 .. _requirements-for-projects:
     documentation.
 
 .. _requirements-for-projects:
@@ -662,93 +666,101 @@ These are the expected kinds of documentation and target audiences for each kind
 Requirements for projects
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Requirements for projects
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Projects MUST do the following
-
-* Provide `AsciiDoc-format <https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Tools:AsciiDoc_Tips>`_ documentation including
+* Projects must 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
 
   * 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 .adoc file or multiple .adoc 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
+    * The feature documentation can be provided as a single ``.rst`` file or
+      multiple ``.rst`` files if the features fall into different groups
+    * Feature documentation should start with appromimately 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)
 
       :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 .adoc file or multiple .adoc files if the features fall into different groups
+    * This documentation should be per-feature, not per-project. Users should
+      not have to know which project a feature came from.
+    * Intimately related features can be documented together. For example,
+      l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be
+      documented as one noting the differences.
+    * This documentation 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.
 
 
   * 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 AsciiDoc) as part of the release review.
+  * 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)
+* Documentation must 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 may be encouraged to instead provide this from their own
+    repository if the tooling is developed
+  * Projects choosing to meet the requirement in 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
+* 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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
 Timeline for Deliverables from Projects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* **M3:** Documentation Started
+* **M2:** Documentation Started
+
+  The following tasks for documentation deliverables must be completed for the
+  M2 readout:
 
 
-  * Identified the kinds of documentation that will be provided and for what
-    features
+  * The kinds of documentation that will be provided and for what features must
+    be identified.
 
 
-    * Release Notes are not required until release reviews at **RC2**
+    .. note:: Release Notes are not required until release reviews at **RC2**
 
 
-  * Created the appropriate .adoc files in the docs repository (or their own
-    repository if the tooling is available)
-  * Have an outline for the expected documentation in those .adoc files
-    including the relevant (sub)sections and a sentence or two explaining what
-    will go there
+  * The appropriate ``.rst`` files must be created in the docs repository
+    (or their own repository if the tooling is available).
+  * An outline for the expected documentation must be completed in those
+    ``.rst`` files including the relevant (sub)sections and a sentence or two
+    explaining what will be contained in these sections.
 
 
-    * Obviusly, providing actual documentation in the (sub)sections is
-      encouraged and meets this requirement
+    .. note:: If an outline is not provided, delivering actual documentation
+              in the (sub)sections meets this requirement.
 
 
-  * Milestone readout should include
+  * M2 readouts should include
 
     #. the list of kinds of documentation
 
     #. the list of kinds of documentation
-    #. the list of corresponding .adoc files and their location, e.g., repo and
-       path
-    #. the list of commits creating those .adoc files
-    #. the current word counts of those .adoc files
+    #. the list of corresponding ``.rst`` files and their location, including
+       repo and path
+    #. the list of commits creating those ``.rst`` files
+    #. the current word counts of those ``.rst`` files
 
 
-* **M4:** Documentation Continues
+* **M3:** Documentation Continues
 
 
-  * The readout at M4 should include the word counts of all .adoc files with
+  * The readout at M3 should include the word counts of all ``.rst`` files with
     links to commits
     links to commits
-  * The goal is to have draft documentation complete so that the documentation
-    group can comment on it.
+  * The goal is to have draft documentation complete at the M3 readout so that
+    the documentation group can comment on it.
 
 
-* **M5:** Documentation Complete
+* **M4:** Documentation Complete
 
 
-  * All (sub)sections in all .adoc files have complete, readable, usable content.
+  * 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
 
   * 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 .adoc pushed to integration (or
-    locally in the project's repository if the tooling is developed)
+  * Projects must provide release notes in ``.rst`` format pushed to integration
+    (or locally in the project's repository if the tooling is developed)
 
 
 
 
-.. _AsciiDoc: http://www.methods.co.nz/asciidoc/
-.. _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
+.. _Sphinx: https://www.sphinx-doc.org/en/master/
+.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+.. _Documentation Group: https://wiki-archive.opendaylight.org/view/Documentation/
+.. _RelEng/Builder: https://wiki-archive.opendaylight.org/view/RelEng/Builder
 .. _Pandoc: http://pandoc.org/
 .. _Pandoc: http://pandoc.org/
-.. _AsciiDoc Tips: https://wiki.opendaylight.org/view/Documentation/Tools/AsciiDoc_Tips