This guide provides details on how to contribute to the OpenDaylight documentation. OpenDaylight currently uses reStructuredText for documentation and Sphinx to build it as it is widely-used to provide both HTML and pdf documentation that can be easily versioned alongside the code. It also offers similar syntax to Markdown which is familiar to large numbers of people.
This section serves two purposes:
That being said, assuming that the content is usable, the bias should be toward merging it rather than blocking on relatively minor edits.
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:
feautre:install
<something>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.
When using reStructuredText, we try to follow the python documentation style guide. See: https://docs.python.org/devguide/documenting.html
The best reference for reStrucutedText syntax seems to be the Sphinx Primer on reStructuredText.
To build and review the reStructuredText documentation locally you must have installed locally:
Which both should be available in most distribution’s package managers.
Then simply run tox and open the html produced via your favorite web browser as follows:
git clone https://git.opendaylight.org/gerrit/docs
cd docs
git submodule update --init
tox
firefox docs/_build/html/index.html
The directory structure for the reStructuredText documentation is
rooted in the docs directory inside the docs git
repository.
Below that there are guides hosted directly in the docs git
repository and there are guides hosted in remote git repositories.
Usually those are for project-specific information.
For example here is the directory layout on June, 28th 2016:
$ tree -L 2
.
├── Makefile
├── conf.py
├── documentation.rst
├── getting-started-guide
│ ├── api.rst
│ ├── concepts_and_tools.rst
│ ├── experimental_features.rst
│ ├── index.rst
│ ├── installing_opendaylight.rst
│ ├── introduction.rst
│ ├── karaf_features.rst
│ ├── other_features.rst
│ ├── overview.rst
│ └── who_should_use.rst
├── index.rst
├── make.bat
├── opendaylight-with-openstack
│ ├── images
│ ├── index.rst
│ ├── openstack-with-gbp.rst
│ ├── openstack-with-ovsdb.rst
│ └── openstack-with-vtn.rst
└── submodules
└── releng
└── builder
The getting-started-guide and opendaylight-with-openstack
directories correspond to two guides hosted in the docs repository,
while the submodules/releng/builder directory houses documentation
for the RelEng/Builder project.
Inside each guide there is usually an index.rst file which then
includes other files using a toctree directive. For example:
.. toctree::
:maxdepth: 1
getting-started-guide/index
opendaylight-with-openstack/index
submodules/releng/builder/docs/index
This creates a table of contents on that page where each heading of the table of contents is the root of the files that are included.
Note
When including rst files using toctree omit the .rst at
the end of the file name.
If you want to import a project underneath the documentation project so
that the docs can be kept in the separate repo, you can do it using the
git submodule add command as follows:
git submodule add -b master ../integration/packaging docs/submodules/integration/packaging
git commit -s
Note
Most projects will not want to use -b master, but instead
use the branch ., which will make track whatever branch
of the documentation project you happen to be on.
Unfortunately, -b . doesn’t work, so you have to manually
edit the .gitmodules file to add branch = . and then
commit it. Something like:
<edit the .gitmodules file>
git add .gitmodules
git commit --amend
When you’re done you should have a git commit something like:
$ git show
commit 7943ce2cb41cd9d36ce93ee9003510ce3edd7fa9
Author: Daniel Farrell <dfarrell@redhat.com>
Date: Fri Dec 23 14:45:44 2016 -0500
Add Int/Pack to git submodules for RTD generation
Change-Id: I64cd36ca044b8303cb7fc465b2d91470819a9fe6
Signed-off-by: Daniel Farrell <dfarrell@redhat.com>
diff --git a/.gitmodules b/.gitmodules
index 91201bf6..b56e11c8 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -38,3 +38,7 @@
path = docs/submodules/ovsdb
url = ../ovsdb
branch = .
+[submodule "docs/submodules/integration/packaging"]
+ path = docs/submodules/integration/packaging
+ url = ../integration/packaging
+ branch = master
diff --git a/docs/submodules/integration/packaging b/docs/submodules/integration/packaging
new file mode 160000
index 00000000..fd5a8185
--- /dev/null
+++ b/docs/submodules/integration/packaging
@@ -0,0 +1 @@
+Subproject commit fd5a81853e71d45945471d0f91bbdac1a1444386
As usual, you can push it to Gerrit with git review.
Important
It’s critical that the Gerrit patch be merged before the git commit hash of the submodule changes. Otherwise, Gerrit won’t be able to automatically keep it up-to-date for you.
As mentioned previously we try to follow the python documentation style guide which defines a few types of sections:
# with overline, for parts
* with overline, for chapters
=, for sections
-, for subsections
^, for subsubsections
", for paragraphs
We try to follow the following structure based on that recommendation:
docs/index.rst -> entry point
docs/____-guide/index.rst -> part
docs/____-guide/<chapter>.rst -> chapter
In the ____-guide/index.rst we use the # with overline at the very top of the file to determine that it is a part and then within each chapter file we start the document with a section using * with overline to denote that it’s the chapter heading and then everything in the rest of the chapter should use:
=, for sections
-, for subsections
^, for subsubsections
", for paragraphs
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.
Within a single document, you can reference another section simply by:
This is a reference to `The title of a section`_
Assuming that somewhere else in the same file there a is a section title something like:
The title of a section
^^^^^^^^^^^^^^^^^^^^^^
It’s typically better to use :ref: syntax and labels to provide
links as they work across files and are resilient to sections being
renamed. First, you need to create a label something like:
.. _a-label:
The title of a section
^^^^^^^^^^^^^^^^^^^^^^
Note
The underscore (_) before the label is required.
Then you can reference the section anywhere by simply doing:
This is a reference to :ref:`a-label`
or:
This is a reference to :ref:`a section I really liked <a-label>`
Note
When using :ref:-style links, you don’t need a trailing
underscore (_).
Because the labels have to be unique, it usually makes sense to prefix
the labels with the project name to help share the label space, e.g.,
sfc-user-guide instead of just user-guide.
As stated in the reStructuredText guide, inline markup for bold, italic, and fixed-width can’t be nested. Further, it can’t be mixed with hyperlinks, so you can’t have bold text link somewhere.
This is tracked in a Docutils FAQ question, but there is no clear current plan to fix this.
If you see an error like this:
./build-integration-robot-libdoc.sh: line 6: cd: submodules/integration/test/csit/libraries: No such file or directory
Resource file '*.robot' does not exist.
It means that you haven’t pulled down the git submodule for the integration/test project. The fastest way to do that is:
git submodule update --init
In some cases, you might wind up with submodules which are somehow out-of-sync and in that case, the easiest way to fix it is delete the submodules directory and then re-clone the submodules:
rm -rf docs/submodules/
git submodule update --init
Warning
This will delete any local changes or information you made in the submodules. This should only be the case if you manually edited files in that directory.
Sometimes, tox will not detect when your requirements.txt file has
changed and so will try to run things without the correct dependencies.
This usually manifests as No module named X errors or
an ExtensionError and can be fixed by deleting the .tox
directory and building again:
rm -rf .tox
tox
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.
As pat of running tox, two environments run: coala which does a variety
of reStructuredText (and other) linting, and docs, which runs Sphinx to
build HTML and PDF documentation. You can run them independently by doing
tox -ecoala or tox -edocs.
The coala linter for reStructuredText isn’t always the most helpful in
explaining why it failed. So, here are some common ones. There should also be
Jenkins Failure Cause Management rules that will highlight these for you.
Coala will check git commit messages for a variety of things including
Some examples of those being logged are:
If you see an error like this:
It seems to mean that the relevant code-block does is not valid for the
language specified, in this case bash. Note that if you specify no language, it
seems as though it assumes the language is python. If you want the code-block
to not be an any particular language, instead use the :: directive. For
example:
Determine the features your project will have and which ones will be ‘’user-facing’‘.
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.
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.
docs.git/docs/templates/template-user-guide.rstddocs/templates/template-developer-guide.rstdocs/templates/template-install-guide.rstNote
You can find the rendered templates here:
Copy the template into the appropriate directory for your project.
docs.git/docs/user-guide/${feature-name}-user-guide.rstdocs.git/docs/developer-guide/${feature-name}-developer-guide.rstdocs.git/docs/getting-started-guide/project-specific-guides/${project-name}.rstNote
These naming conventions aren’t set in stone, but do help. If you think there’s a better name, use it and we’ll give feedback on the gerrit patch.
Edit the template to fill in the outline of what you will provide using the suggestions in the template. If you feel like a section isn’t needed, feel free to omit it.
Link the template into the appropriate core rst file
docs.git/docs/user-guide/index.rstdocs.git/docs/developer-guide/index.rstdocs.git/docs/getting-started-guide/project-specific-guides/index.rstproject-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.
tox from the root of the cloned docs repo.docs.git/docs/_build/html/index.html.Commit and submit the patch
Commit using:
git add --all && git commit -sm "Documentation outline for ${project-shortname}"
Submit using:
git review
See the Git-review Workflow page if you don’t have git-review installed.
Wait for the patch to be merged or to get feedback
The expected output is (at least) 3 PDFs and equivalent web-based documentation:
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.
These are the expected kinds of documentation and target audiences for each kind.
Projects MUST do the following