###################
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
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.
-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
----------------------
-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
-* 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
-* Project: a project within OpenDaylight, projects ship features to
+* Project: a project within OpenDaylight; projects ship features to
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
* 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.
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
-* 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
* 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
* 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
+When using reStructuredText, follow the Python documentation
+style guidelines. See: https://docs.python.org/devguide/documenting.html
-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_.
-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
-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
git clone https://git.opendaylight.org/gerrit/docs
cd docs
git submodule update --init
- tox -edocs
+ tox
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
-------------------
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
.
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
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.
-.. 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
------------------------------
-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
^, 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
-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
-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
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
+This section provides a quick primer for creating references
+in OpenDaylight documentation. For more information, refer to
+`Cross-referencing documents
<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
+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
+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::
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``.
+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
---------------
-Nested formatting doesn't work
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Nested formatting does not 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.
+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
<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
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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.
-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
-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
-.. 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.
-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.
-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
- tox -edocs
+ 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.
+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.
-As an example, this patch:
+As an example, refer to the following 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
-
-Migration from AsciiDoc to ReStructuredText
-===========================================
-
-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
==================================
-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
- 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.
-#. 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.
- * 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``
-#. 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.
- * 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
-#. Commit and submit the patch
+#. Commit and submit the patch.
#. Commit using:
#. 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
------------------------------------------
* 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 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 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
- .. 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
- .. 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
- * 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
- 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
* **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:
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
- * 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)
- * ''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.
- * 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-* **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 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
- * 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
- * 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
.. _Pandoc: http://pandoc.org/
-.. _AsciiDoc Tips: https://wiki.opendaylight.org/view/Documentation/Tools/AsciiDoc_Tips