+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.
+
+Errors from ``Coala``
+^^^^^^^^^^^^^^^^^^^^^
+
+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``.
+
+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.
+
+Git Commit Message Errors
+"""""""""""""""""""""""""
+
+``Coala`` checks that git commit messages adhere to the following rules:
+
+* ``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.
+
+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 means that the relevant code-block is not valid for the
+language specified, in this case ``bash``.
+
+.. 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 particular language
+
+Project Documentation Requirements
+==================================
+
+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
+ 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.
+
+#. 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.
+
+ .. 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 repository: ``git clone https://git.opendaylight.org/gerrit/docs``
+#. For each piece of documentation find the corresponding template in the docs
+ repository.
+
+ * 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 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.
+
+#. 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.
+
+#. 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 repository.
+
+ * 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-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.
+ * 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
+------------------------------------------
+
+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:: 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.
+
+Project Documentation Requirements
+----------------------------------
+
+.. _kinds-of-docs:
+
+Content Types
Code Review / docs.git / blobdiff