###################
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
====================================
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
---------------
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.
-
-Bold/Italics/Verbatim Formatting
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This is mostly minor syntax issues. In AsciiDoc you do inline
-formatting something like this::
-
- *bold* _italic_ +verbatim+ `verbatim`
-
-In reStructuredText, things are slightly different::
-
- **bold** *italic* ``verbatim``
-
-Images
-^^^^^^
-
-Image formats change from something like::
-
- .OpenStack Architecture
- image::vtn/OpenStackDeveloperGuide.png["OpenStack Architecture",width=500]
-
-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
-
-
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/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 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.
- 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 -edocs`` 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
--- /dev/null
+####################
+<Feature> User Guide
+####################
+
+Refer to this template to identify the required sections and information
+that you should provide for a User Guide. The user guide should contain
+configuration, administration, management, using, and troubleshooting
+sections for the feature.
+
+Overview
+========
+
+Provide an overview of the feature and the use case. Also include the
+audience who will use the feature. For example, audience can be the
+network administrator, cloud administrator, network engineer, system
+administrators, and so on.
+
+<Feature> Architecture
+======================
+
+Provide information about feature components and how they work together.
+Also include information about how the feature integrates with
+OpenDaylight. An architecture diagram could help.
+
+.. note:: Please *do not* include detailed internals that somebody
+ using the feature wouldn't care about. For example, the fact
+ that there are four layers of APIs between a user command and
+ a message being sent to a device is probably not useful to
+ know unless they have some way to influence how those layers
+ work and a reason to do so.
+
+
+Configuring <feature>
+=====================
+
+Describe how to configure the feature or the project after installation.
+Configuration information could include day-one activities for a project
+such as configuring users, configuring clients/servers and so on.
+
+Administering or Managing <feature>
+===================================
+
+Include related command reference or operations that you could perform
+using the feature. For example viewing network statistics, monitoring
+the network, generating reports, and so on.
+
+.. note: Ensure that you create a step procedure whenever required and
+ avoid concepts.
+
+For example:
+
+To configure L2switch components perform the following steps.
+
+#. Step 1:
+#. Step 2:
+#. Step 3:
+
+Tutorials
+=========
+
+*optional*
+
+If there is only one tutorial, you skip the "Tutorials" section and
+instead just lead with the single tutorial's name. If you do, also
+increase the header level by one, i.e., replace the carets (^^^) with
+dashes (- - -) and the dashes with equals signs (===).
+
+<Tutorial Name>
+---------------
+
+Ensure that the title starts with a gerund. For example using,
+monitoring, creating, and so on.
+
+Overview
+^^^^^^^^
+
+An overview of the use case.
+
+Prerequisites
+^^^^^^^^^^^^^
+
+Provide any prerequisite information, assumed knowledge, or environment
+required to execute the use case.
+
+Target Environment
+^^^^^^^^^^^^^^^^^^
+
+Include any topology requirement for the use case. Ideally, provide
+visual (abstract) layout of network diagrams and any other useful visual
+aides.
+
+Instructions
+^^^^^^^^^^^^
+
+Use case could be a set of configuration procedures. Including
+screenshots to help demonstrate what is happening is especially useful.
+Ensure that you specify them separately. For example:
+
+Setting up the VM
+"""""""""""""""""
+
+To set up a VM perform the following steps.
+
+#. Step 1
+#. Step 2
+#. Step 3
+
+Installing the feature
+""""""""""""""""""""""
+
+To install the feature perform the following steps.
+
+#. Step 1
+#. Step 2
+#. Step 3
+
+Configuring the environment
+"""""""""""""""""""""""""""
+
+To configure the system perform the following steps.
+
+#. Step 1
+#. Step 2
+#. Step 3
Code Review / docs.git / commitdiff