X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fdocumentation.rst;h=a3e15986ea205ebfa04b4eb1b6a51087b1339059;hb=7b1fe39eaf48ff5c20f2e2d9c07d62fb68b0744f;hp=a801ec0f298b06a979f4eeaaee2f755c5b750138;hpb=f84901ff399e884b5a766705a3e3c1f07986b168;p=docs.git diff --git a/docs/documentation.rst b/docs/documentation.rst index a801ec0f2..a3e15986e 100644 --- a/docs/documentation.rst +++ b/docs/documentation.rst @@ -5,16 +5,14 @@ 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: 1 + :depth: 2 :local: Style Guide @@ -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,20 +74,22 @@ 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 +* 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 @@ -96,12 +98,12 @@ capitalization and spacing.* * 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. +* Open vSwitch: not OpenvSwitch, OpenVSwitch, or Open V Switch. +* OpenDaylight: not Opendaylight, Open Daylight, or OpenDayLight. - * also avoid abbreviations like ODL and ODC + .. note:: Also, avoid Opendaylight abbreviations like ODL and ODC. -* OpenFlow: not Openflow, Open Flow, openflow, etc. +* OpenFlow: not Openflow, Open Flow, or openflow. * OpenStack: not Open Stack or Openstack * QoS: not Qos, QOS, or qos * RESTCONF: not Restconf or restconf @@ -110,24 +112,27 @@ capitalization and spacing.* * 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://docs.python.org/devguide/documenting.html -The best reference for reStrucutedText syntax seems to be the Sphinx +One of the best references for reStrucutedText 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 repo, 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 @@ -233,188 +298,469 @@ the chapter should use:: ^, for subsubsections ", for paragraphs +Referencing Sections +^^^^^^^^^^^^^^^^^^^^ + +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 +title something like:: + + The title of a section + ^^^^^^^^^^^^^^^^^^^^^^ + +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:: + + .. _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 ` + + +.. note:: When using ``:ref:``-style links, you don't need a trailing + underscore (_). + +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``. + + +.. _docs-rst-troubleshooting: Troubleshooting --------------- -Make sure you've cloned submodules -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Nested formatting does not work +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As stated in the reStructuredText_ guide, inline markup for bold, +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 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 -AsciiDoc-based Documentation -============================ +Builds on Read the Docs +^^^^^^^^^^^^^^^^^^^^^^^ -Information on the AsciiDoc tools and build system can be found here: -https://wiki.opendaylight.org/view/Documentation/Tools +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. -Directory Structure -------------------- +As an example, refer to the following patch: +https://git.opendaylight.org/gerrit/41679 -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:: +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. - $ 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. +Errors from Coala +^^^^^^^^^^^^^^^^^^ -Troubleshooting ---------------- +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``. + +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. + +Git Commit Message Errors +""""""""""""""""""""""""" + +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, + "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. + +Some examples of those being logged are: + +:: + Project wide: + | | [NORMAL] GitCommitBear: + | | Shortlog of HEAD commit isn't in imperative mood! Bad words are 'Adding' + +:: + Project wide: + | | [NORMAL] GitCommitBear: + | | Body of HEAD commit contains too long lines. Commit body lines should not exceed 72 characters. + +Error in "code-block" directive +""""""""""""""""""""""""""""""" + +If you see an error like this: + +:: + docs/gerrit.rst + | 89| ···..·code-block::·bash + | | [MAJOR] RSTcheckBear: + | | (ERROR/3) Error in "code-block" directive: + +It means that the relevant code-block is not valid for the +language specified, in this case ``bash``. + +.. 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 particluar langauge + +Project Documentation Requirements +================================== + +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 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 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:: 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. + +#. 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/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`` + + .. note:: You can find the rendered templates here: + + .. toctree:: + :maxdepth: 1 + + templates/template-user-guide + templates/template-developer-guide + templates/template-install-guide.rst + + +#. 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`` + + .. 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. + +#. 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. + +#. Link the template into the appropriate core ``.rst`` file. + + * 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 ``tox`` from the root of the cloned docs repo. + + * 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 :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 using: + + .. code-block:: bash + + git add --all && git commit -sm "Documentation outline for ${project-shortname}" + + #. Submit using: + + .. code-block:: bash + + git review + + See the `Git-review Workflow `_ + page if you don't have git-review installed. + +#. Wait for the patch to be merged or to get feedback + + * If you get feedback, make the requested changes and resubmit the patch. + * 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 +------------------------------------------ + +The expected output is (at least) 3 PDFs and equivalent web-based documentation: + +* User/Operator Guide +* Developer Guide +* 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:: 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: + +Content Types +^^^^^^^^^^^^^ + +These are the expected kinds of documentation and target audiences for each +kind. + +* **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 + do + +* **Developer:** for people looking to use the feature in code without modifying + it + + * 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:: 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:: 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 + * 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 + 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 + + * 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 + documentation + + * Generally, these should be done as a (sub)section of either user/operator + or developer documentation. + * If they are especially long or complex, they may belong on their own + +* **Release Notes:** + + * Release notes are required as part of each project's release review. They + must also be translated into reStructuredText for inclusion in the formal + documentation. + +.. _requirements-for-projects: + +Requirements for projects +^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Projects must provide reStructuredText documentation including: -See `AsciiDoc Tips`_ on the wiki for more information. + * Developer documentation for every feature -Common AsciiDoc mistakes -^^^^^^^^^^^^^^^^^^^^^^^^ + * Most projects will want to logically nest the documentation for + 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 + of the project and include references to any automatically-generated API + documentation as well as more general developer information (see + :ref:`kinds-of-docs`). -See also `AsciiDoc Tips`_. + * User/Operator documentation for every every user-facing feature (if any) -* 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 + * 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 -Migration from AsciiDoc to ReStructuredText -=========================================== + * Installation documentation -Automatically -------------- + * Most projects will simply provide a list of user-facing features and + options. See :ref:`kinds-of-docs` above. -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. + * Release Notes (both on the wiki and reStructuredText) as part of the release + review. -By Hand -------- +* Documentation must be contributed to the docs repo (or possibly imported + from the project's own repo with tooling that is under development) -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. + * 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 -The differences are usually minor and fast to change. +* Projects must cooperate with the documentation group on edits and enhancements + to documentation -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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Timeline for Deliverables from Projects +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This is mostly minor syntax issues. In AsciiDoc you do inline -formatting something like this:: +* **M2:** Documentation Started - *bold* _italic_ +verbatim+ `verbatim` + The following tasks for documentation deliverables must be completed for the + M2 readout: -In reStructuredText, things are slightly different:: + * The kinds of documentation that will be provided and for what features must + be identified. - **bold** *italic* ``verbatim`` + .. note:: Release Notes are not required until release reviews at **RC2** -Images -^^^^^^ + * 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. -Image formats change from something like:: + .. note:: If an outline is not provided, delivering actual documentation + in the (sub)sections meets this requirement. - .OpenStack Architecture - image::vtn/OpenStackDeveloperGuide.png["OpenStack Architecture",width=500] + * M2 readouts should include -To something like:: + #. the list of kinds of documentation + #. the list of corresponding ``.rst`` files and their location, including + repo and path + #. the list of commits creating those ``.rst`` files + #. the current word counts of those ``.rst`` files - .. image:: images/dlux-default.png +* **M3:** Documentation Continues -A helpful regular expression for automating the replacements is -something like:: + * 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 at the M3 readout so that + the documentation group can comment on it. - search: ^( *)\.(.+)\n +image::(.+)\[(.+),width=(\d+)\] - replace: $1.. figure:: images/dlux/$3\n$1 :width: $5\n\n$1 $2 +* **M4:** Documentation Complete + * 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 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 .. _Pandoc: http://pandoc.org/ -.. _AsciiDoc Tips: https://wiki.opendaylight.org/view/Documentation/Tools/AsciiDoc_Tips