X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fdocumentation.rst;h=2e427b15a9ca7ec9789f5970dd504cfbdce2d91e;hb=HEAD;hp=d06930b2e95b336aad80a9566236712f0bb5d71e;hpb=ff8af58ed9fdb8c9e66a33e2dce084cad898b76a;p=docs.git diff --git a/docs/documentation.rst b/docs/documentation.rst index d06930b2e..2e427b15a 100644 --- a/docs/documentation.rst +++ b/docs/documentation.rst @@ -5,13 +5,11 @@ Documentation Guide ################### 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 @@ -22,31 +20,33 @@ Style Guide 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 @@ -58,7 +58,7 @@ Common writing style mistakes * 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 `` * Avoid statements which are true about part of OpenDaylight, but not generally true. @@ -74,60 +74,65 @@ Common writing style mistakes 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 +* 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, etc. -* OpenDaylight: not Opendaylight, Open Daylight, or OpenDayLight, etc. - - * also avoid abbreviations like ODL and ODC - -* OpenFlow: not Openflow, Open Flow, openflow, etc. -* 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: + 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://devguide.python.org/documenting/ -The best reference for reStrucutedText syntax seems to be 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 -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 @@ -135,12 +140,9 @@ browser as follows: 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 ------------------- @@ -148,11 +150,12 @@ 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. +.. 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 . @@ -187,8 +190,8 @@ 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:: +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 @@ -197,17 +200,78 @@ includes other files using a ``toctree`` directive. For example:: 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 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 + 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:: + + + 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 + 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 + + 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 @@ -216,16 +280,17 @@ guide which defines a few types of sections:: ^, 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/.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 @@ -236,23 +301,22 @@ the chapter should use:: 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 +`_. 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:: @@ -271,283 +335,242 @@ or:: This is a reference to :ref:`a section I really liked ` + .. 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``. + +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: 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 -`_, +`_, 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. - -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. - -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. +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. -By Hand -------- +As an example, refer to the following patch: +https://git.opendaylight.org/gerrit/c/docs/+/41679/ -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. +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. -The differences are usually minor and fast to change. +Errors from ``Coala`` +^^^^^^^^^^^^^^^^^^^^^ -Also, because of how fast Sphinx builds, and how fast it is to refresh -the HTML documentation rapid iteration is very easy. +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``. -Bold/Italics/Verbatim Formatting -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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. -This is mostly minor syntax issues. In AsciiDoc you do inline -formatting something like this:: +Git Commit Message Errors +""""""""""""""""""""""""" - *bold* _italic_ +verbatim+ `verbatim` +``Coala`` checks that git commit messages adhere to the following rules: -In reStructuredText, things are slightly different:: +* ``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. - **bold** *italic* ``verbatim`` +Some examples of those being logged are: -Images -^^^^^^ +:: + Project wide: + | | [NORMAL] GitCommitBear: + | | ``Shortlog`` of HEAD commit isn't in imperative mood! Bad words are 'Adding' -Image formats change from something like:: +:: + Project wide: + | | [NORMAL] GitCommitBear: + | | Body of HEAD commit contains too long lines. Commit body lines should not exceed 72 characters. - .OpenStack Architecture - image::vtn/OpenStackDeveloperGuide.png["OpenStack Architecture",width=500] +Error in "code-block" directive +""""""""""""""""""""""""""""""" -To something like:: +If you see an error like this: - .. figure:: images/dlux-default.png +:: + ``docs/gerrit.rst`` + | 89| ···..·code-block::·bash + | | [MAJOR] RSTcheckBear: + | | (ERROR/3) Error in "code-block" directive: -A helpful regular expression for automating the replacements is -something like:: +It means that the relevant code-block is not valid for the +language specified, in this case ``bash``. - 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 particular language 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. -#. 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. + .. 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. - * 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`` +#. Clone the docs repository: ``git clone https://git.opendaylight.org/gerrit/docs`` +#. For each piece of documentation find the corresponding template in the docs + repository. -#. Copy the template into the appropriate directory for your project. + * 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`` - * 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`` + .. note:: You can find the rendered templates here: -#. Edit the template to fill in the outline of what you will provide using the - suggestions in the template. + .. toctree:: + :maxdepth: 1 + + 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 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. - .. 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 is not 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 repository. - * 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 `_ - page provide common errors and solutions. + * The :ref:`reStructuredText 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: @@ -561,19 +584,15 @@ Submitting Documentation Outlines (M3) git review - See the `Git-review Workflow `_ + 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 * 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 ------------------------------------------ @@ -585,58 +604,60 @@ The expected output is (at least) 3 PDFs and equivalent web-based documentation: * 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. -Boron Project Documentation Requirements ----------------------------------------- +.. 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. + +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 available 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 + 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 @@ -644,7 +665,7 @@ These are the expected kinds of documentation and target audiences for each kind * 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 @@ -654,7 +675,7 @@ These are the expected kinds of documentation and target audiences for each kind * **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: @@ -662,93 +683,101 @@ These are the expected kinds of documentation and target audiences for each kind Requirements for projects ^^^^^^^^^^^^^^^^^^^^^^^^^ -Projects MUST do the following - -* Provide `AsciiDoc-format `_ 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 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`). * 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 imported from the project own repository or contributed + to the docs repository for generic information. - * 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 repository 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 + repository 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 +.. _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/ -.. _AsciiDoc Tips: https://wiki.opendaylight.org/view/Documentation/Tools/AsciiDoc_Tips