###################
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 as it is widely-used to provide
+both HTML and pdf documentation that can be easily versioned alongside
+the code. It also offers similar syntax to Markdown which is familiar
+to large numbers of people.
.. contents:: Contents
:depth: 2
* VM: not Vm or vm
* YANG: not Yang or yang
+.. _docs-rst:
+
reStructuredText-based Documentation
====================================
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
-------------------
.. note:: When including rst files using ``toctree`` omit the .rst at
the end of the file name.
+Adding a submodule
+^^^^^^^^^^^^^^^^^^
+
+If you want to import a project underneath the documentation project so
+that the docs can be kept in the separate repo, you can do it using the
+``git submodule add`` command as follows::
+
+ git submodule add -b master ../integration/packaging docs/submodules/integration/packaging
+ git commit -s
+
+.. note:: Most projects will not want to use ``-b master``, but instead
+ use the branch ``.``, which will make track whatever branch
+ of the documentation project you happen to be on.
+
+ Unfortunately, ``-b .`` doesn't work, so you have to manually
+ edit the ``.gitmodules`` file to add ``branch = .`` and then
+ commit it. Something like::
+
+ <edit the .gitmodules file>
+ git add .gitmodules
+ git commit --amend
+
+When you're done you should have a git commit something like::
+
+ $ git show
+ commit 7943ce2cb41cd9d36ce93ee9003510ce3edd7fa9
+ Author: Daniel Farrell <dfarrell@redhat.com>
+ Date: Fri Dec 23 14:45:44 2016 -0500
+
+ Add Int/Pack to git submodules for RTD generation
+
+ Change-Id: I64cd36ca044b8303cb7fc465b2d91470819a9fe6
+ Signed-off-by: Daniel Farrell <dfarrell@redhat.com>
+
+ diff --git a/.gitmodules b/.gitmodules
+ index 91201bf6..b56e11c8 100644
+ --- a/.gitmodules
+ +++ b/.gitmodules
+ @@ -38,3 +38,7 @@
+ path = docs/submodules/ovsdb
+ url = ../ovsdb
+ branch = .
+ +[submodule "docs/submodules/integration/packaging"]
+ + path = docs/submodules/integration/packaging
+ + url = ../integration/packaging
+ + branch = master
+ diff --git a/docs/submodules/integration/packaging b/docs/submodules/integration/packaging
+ new file mode 160000
+ index 00000000..fd5a8185
+ --- /dev/null
+ +++ b/docs/submodules/integration/packaging
+ @@ -0,0 +1 @@
+ +Subproject commit fd5a81853e71d45945471d0f91bbdac1a1444386
+
+As usual, you can push it to Gerrit with ``git review``.
+
+.. important:: It's critical that the Gerrit patch be merged before the
+ git commit hash of the submodule changes. Otherwise,
+ Gerrit won't be able to automatically keep it up-to-date
+ for you.
+
Documentation Layout and Style
------------------------------
^, for subsubsections
", for paragraphs
+Referencing Sections
+^^^^^^^^^^^^^^^^^^^^
+
+It's pretty common to want to reference another location in the
+OpenDaylight documentation and it's pretty easy to do with
+reStructuredText. This is a quick primer, more information is in the
+`Sphinx section on Cross-referencing arbitrary locations
+<http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.
+
+Within a single document, you can reference another section simply by::
+
+ This is a reference to `The title of a section`_
+
+Assuming that somewhere else in the same file there a is a section
+title something like::
+
+ The title of a section
+ ^^^^^^^^^^^^^^^^^^^^^^
+
+It's typically better to use ``:ref:`` syntax and labels to provide
+links as they work across files and are resilient to sections being
+renamed. First, you need to create a label something like::
+
+ .. _a-label:
+
+ The title of a section
+ ^^^^^^^^^^^^^^^^^^^^^^
+
+.. note:: The underscore (_) before the label is required.
+
+Then you can reference the section anywhere by simply doing::
+
+ This is a reference to :ref:`a-label`
+
+or::
+
+ This is a reference to :ref:`a section I really liked <a-label>`
+
+.. note:: When using ``:ref:``-style links, you don't need a trailing
+ underscore (_).
+
+Because the labels have to be unique, it usually makes sense to prefix
+the labels with the project name to help share the label space, e.g.,
+``sfc-user-guide`` instead of just ``user-guide``.
+
+
+.. _docs-rst-troubleshooting:
+
Troubleshooting
---------------
with hyperlinks, so you can't have bold text link somewhere.
This is tracked in a `Docutils FAQ question
-<http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible>`,
+<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
in the submodules. This should only be the case 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
directory and building again::
rm -rf .tox
- tox -edocs
+ tox
Builds on Read the Docs
^^^^^^^^^^^^^^^^^^^^^^^
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
--------------
-
-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.
-
-By Hand
--------
-
-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 differences are usually minor and fast to change.
-
-Also, because of how fast Sphinx builds, and how fast it is to refresh
-the HTML documentation rapid iteration is very easy.
+Weird Errors from Coala
+^^^^^^^^^^^^^^^^^^^^^^^
-Bold/Italics/Verbatim Formatting
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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``.
-This is mostly minor syntax issues. In AsciiDoc you do inline
-formatting something like this::
+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.
- *bold* _italic_ +verbatim+ `verbatim`
+Git Commit Message Errors
+"""""""""""""""""""""""""
-In reStructuredText, things are slightly different::
+Coala will check git commit messages for a variety of things including
- **bold** *italic* ``verbatim``
+* Shortlog (1st line of commit message) is less than 50 characters
+* Shortlog (1st line of commit message) is in the imperative mood, e.g., "Add
+ foo unit test" is good, but "Adding foo unit test is bad""
+* Body (all lines but 1st line of commit message) are less than 72 characters.
+ Some exceptions seem to exist, e.g., for long URLs.
-Images
-^^^^^^
+Some examples of those being logged are:
-Image formats change from something like::
+::
+ Project wide:
+ | | [NORMAL] GitCommitBear:
+ | | Shortlog of HEAD commit isn't in imperative mood! Bad words are 'Adding'
- .OpenStack Architecture
- image::vtn/OpenStackDeveloperGuide.png["OpenStack Architecture",width=500]
+::
+ Project wide:
+ | | [NORMAL] GitCommitBear:
+ | | Body of HEAD commit contains too long lines. Commit body lines should not exceed 72 characters.
-To something like::
+Error in "code-block" directive
+"""""""""""""""""""""""""""""""
- .. figure:: images/dlux-default.png
+If you see an error like this:
-A helpful regular expression for automating the replacements is
-something like::
+::
+ docs/gerrit.rst
+ | 89| ···..·code-block::·bash
+ | | [MAJOR] RSTcheckBear:
+ | | (ERROR/3) Error in "code-block" directive:
- search: ^( *)\.(.+)\n +image::(.+)\[(.+),width=(\d+)\]
- replace: $1.. figure:: images/dlux/$3\n$1 :width: $5\n\n$1 $2
+It seems to mean that the relevant code-block does is not valid for the
+language specified, in this case bash. Note that if you specify no language, it
+seems as though it assumes the language is python. If you want the code-block
+to not be an any particular language, instead use the ``::`` directive. For
+example:
+::
+ ::
+ This is a code block
+ that will not be parsed
+ in any particluar langauge
Project Documentation Requirements
==================================
#. Clone the docs repo: ``git clone https://git.opendaylight.org/gerrit/docs``
#. For each piece of documentation find the corresponding template in the docs repo.
- * For user documentation: ``docs.git/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/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``
- * 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:
+ .. note:: These naming conventions aren't set in stone, but do help. If you
+ think there's a better name, use it and we'll give feedback on the
+ gerrit patch.
- .. code-block:: none
+#. 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.
- include::${project-shortname}/${feature-name}-user.adoc[]
+#. Link the template into the appropriate core rst file
- * Make sure there is a blank line between your include statement and any others as this prevents sections from running into each other.
+ * 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
.. note:
- should be documented on the wiki not in asciidoc
+ should be documented on the wiki not in reStructuredText
* **Installation:** for people looking for instructions to install the feature
after they have downloaded the ODL release
* **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:
Projects MUST do the following
-* Provide `AsciiDoc-format <https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Tools:AsciiDoc_Tips>`_ documentation including
+* 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
+ * This can be provided as a single .rst file or multiple .rst files if
the features fall into different groups
* This should start with ~300 word overview of the project and include
references to any automatically-generated API documentation as well as
* ''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 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)
* Release Notes are not required until release reviews at **RC2**
- * Created the appropriate .adoc files in the docs repository (or their own
+ * Created the appropriate .rst files in the docs repository (or their own
repository if the tooling is available)
- * Have an outline for the expected documentation in those .adoc files
+ * Have an outline for the expected documentation in those .rst files
including the relevant (sub)sections and a sentence or two explaining what
will go there
* Milestone readout should include
#. the list of kinds of documentation
- #. the list of corresponding .adoc files and their location, e.g., repo and
+ #. the list of corresponding .rst 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 commits creating those .rst files
+ #. the current word counts of those .rst files
* **M4:** Documentation Continues
- * The readout at M4 should include the word counts of all .adoc files with
+ * The readout at M4 should include the word counts of all .rst files with
links to commits
* The goal is to have draft documentation complete so that the documentation
group can comment on it.
* **M5:** Documentation Complete
- * All (sub)sections in all .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
+ * Projects must provide release notes as .rst 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
Code Review / docs.git / blobdiff