exact capitalization and spacing associated with the URL or class
name.
-* ACL: not Acl or acl
-* API: not api
-* ARP: not Arp or arp
+* ACL: not ``Acl`` or ``acl``
+* API: not ``api``
+* ARP: not ``Arp`` or ``arp``
* 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
+* ``IPsec``: not IPSEC or ``ipsec``
+* ``IPv4`` or ``IPv6``: not ``Ipv4``, ``Ipv6``, ``ipv4``, ``ipv6``, ``IPV4``, or ``IPV6``
* Karaf: not karaf
-* Linux: not LINUX or linux
+* Linux: not LINUX or ``linux``
* NETCONF: not Netconf or netconf
* Neutron: not neutron
-* OSGi: not osgi or OSGI
-* Open vSwitch: not OpenvSwitch, OpenVSwitch, or Open V Switch.
-* OpenDaylight: not Opendaylight, Open Daylight, or OpenDayLight.
-
- .. note:: Also, avoid Opendaylight abbreviations like ODL and ODC.
-
-* OpenFlow: not Openflow, Open Flow, or openflow.
-* OpenStack: not Open Stack or Openstack
-* QoS: not Qos, QOS, or qos
-* RESTCONF: not Restconf or restconf
-* RPC not Rpc or rpc
-* URL not Url or url
-* VM: not Vm or vm
+* OSGi: not ``osgi`` or OSGI
+* ``Open vSwitch``: not OpenvSwitch, OpenVSwitch, or Open V Switch.
+* OpenDaylight: not ``Opendaylight``, ``Open Daylight``, or ``OpenDayLight``.
+
+ .. note:: Also, avoid OpenDaylight abbreviations such as ODL and OD.
+
+* OpenFlow: not ``Openflow``, ``Open Flow``, or ``openflow``.
+* OpenStack: not ``Open Stack`` or ``Openstack``
+* QoS: not ``Qos``, ``QOS``, or ``qos``
+* RESTCONF: not ``Restconf`` or ``restconf``
+* RPC not ``Rpc`` or ``rpc``
+* URL not ``Url`` or ``url``
+* VM: not ``Vm`` or ``vm``
* YANG: not Yang or yang
.. _docs-rst:
====================================
When using reStructuredText, follow the Python documentation
-style guidelines. See: https://docs.python.org/devguide/documenting.html
+style guidelines. See: https://devguide.python.org/documenting/
-One of the best references for reStrucutedText syntax is the Sphinx
+One of the best references for reStructuredText syntax is the Sphinx
Primer on reStructuredText_.
To build and review the reStructuredText documentation locally, you must
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
.
^^^^^^^^^^^^^^^^^^
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
+that the docs can be kept in the separate repository, you can do it by using the
``git submodule add`` command as follows::
git submodule add -b master ../integration/packaging docs/submodules/integration/packaging
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 is the chapter heading and then everything in the rest of
the labels with the project name to help share the label space; for example,
use ``sfc-user-guide`` instead of just ``user-guide``.
+Referencing JIRA issues
+^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to reference JIRA, we provide two new directives, ``jira_fixed_issues`` and
+``jira_known_issues``. These render a table of issues for a particular project and
+its version range. These are used like this:
+
+ .. code-block:: rst
+
+ .. jira_fixed_issues::
+ :project: CONTROLLER
+ :versions: 4.0.0-4.0.3
+
+ .. jira_known_issues::
+ :project: CONTROLLER
+ :versions: 4.0.0-4.0.3
+
.. _docs-rst-troubleshooting:
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>`_,
+<https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible>`_,
but there is no clear current plan to fix this.
Make sure you have cloned submodules
old runs of the build script.
As an example, refer to the following patch:
-https://git.opendaylight.org/gerrit/41679
+https://git.opendaylight.org/gerrit/c/docs/+/41679/
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.
+Javadoc files that were present from previous runs.
-Errors from Coala
-^^^^^^^^^^^^^^^^^^
+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
Git Commit Message Errors
"""""""""""""""""""""""""
-Coala checks that git commit messages adhere to the following rules:
+``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,
+* ``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.
::
Project wide:
| | [NORMAL] GitCommitBear:
- | | Shortlog of HEAD commit isn't in imperative mood! Bad words are 'Adding'
+ | | ``Shortlog`` of HEAD commit isn't in imperative mood! Bad words are 'Adding'
::
Project wide:
If you see an error like this:
::
- docs/gerrit.rst
+ ``docs/gerrit.rst``
| 89| ···..·code-block::·bash
| | [MAJOR] RSTcheckBear:
| | (ERROR/3) Error in "code-block" directive:
::
This is a code block
that will not be parsed
- in any particluar langauge
+ in any particular language
Project Documentation Requirements
==================================
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``
+#. Clone the docs repository: ``git clone https://git.opendaylight.org/gerrit/docs``
#. For each piece of documentation find the corresponding template in the docs
- repo.
+ repository.
* For user documentation: ``docs.git/docs/templates/template-user-guide.rst``
* For developer documentation: ``ddocs/templates/template-developer-guide.rst``
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.
+ 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
#. Make sure the documentation project still builds.
- * Run ``tox`` from the root of the cloned docs repo.
+ * 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``.
git review
- See the `Git-review Workflow <https://wiki.opendaylight.org/view/Git-review_Workflow>`_
+ 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
* **User/Operator:** for people looking to use the feature without writing code
* Should include an overview of the project/feature
- * Should include description of availble configuration options and what they
+ * Should include description of available configuration options and what they
do
* **Developer:** for people looking to use the feature in code without modifying
options
* As an example, l2switch-switch as the top-level feature with the -rest
- and -ui options
- * 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
+ and ``-ui`` options
+ * Features should also note if the options should be check-boxes (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 an automated installer or configurator
+ or even downloader.
* For some projects, there is extra installation instructions (for external
components) and/or configuration
* In that case, there will be a (sub)section in the documentation
describing this process.
-* **HowTo/Tutorial:** walk throughs and examples that are not general-purpose
+* **HowTo/Tutorial:** walk-through and examples that are not general-purpose
documentation
* Generally, these should be done as a (sub)section of either user/operator
individual features under a single project-wide chapter or section
* 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
+ * Feature documentation should start with approximately 300 words 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`).
* 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.
+ ``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
* Release Notes (both on the wiki and reStructuredText) as part of the release
review.
-* Documentation must be contributed to the docs repo (or possibly imported
- from the project's own repo with tooling that is under development)
+* Documentation must be imported from the project own repository or contributed
+ to the docs repository for generic information.
* 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
+ to docs repository to import the project's documentation
* Projects must cooperate with the documentation group on edits and enhancements
to documentation
#. the list of kinds of documentation
#. the list of corresponding ``.rst`` files and their location, including
- repo and path
+ repository and path
#. the list of commits creating those ``.rst`` files
#. the current word counts of those ``.rst`` files
(or locally in the project's repository if the tooling is developed)
-.. _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
+.. _Sphinx: https://www.sphinx-doc.org/en/master/
+.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+.. _Documentation Group: https://wiki-archive.opendaylight.org/view/Documentation/
+.. _RelEng/Builder: https://wiki-archive.opendaylight.org/view/RelEng/Builder
.. _Pandoc: http://pandoc.org/