X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fdocumentation.rst;h=11fdc3265d2108f12707fa43df23bcf26b5fbad2;hb=78c5f85a3449e93ab8fee34e9de250df5b5d02cc;hp=45a899f98f4ea9c9aad0e39ea83c74362367df0f;hpb=f6f2d4b3ceeecc49df0ffc132b639969c900275e;p=docs.git diff --git a/docs/documentation.rst b/docs/documentation.rst index 45a899f98..11fdc3265 100644 --- a/docs/documentation.rst +++ b/docs/documentation.rst @@ -1,25 +1,302 @@ .. _documentation-guide: +################### Documentation Guide -=================== +################### -This guide provides details on how to contribute to the documetantion of -Spectrometer. The style guide we follow for documentation is the python -documentation style guide. See: +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. - https://docs.python.org/devguide/documenting.html +reStructuredText-based Documentation +==================================== -To build and review the documentation locally you first require to have -installed locally: +When using reStructuredText, we try to follow the python documentation +style guide. See: https://docs.python.org/devguide/documenting.html + +To build and review the reStructuredText documentation locally you must +have installed locally: * python * python-tox Which both should be available in most distribution's package managers. -Then simply run tox and open the html produced via your favourite web browser. +Then simply run tox and open the html produced via your favorite web +browser as follows: .. code-block:: bash - tox -edocs - firefox .tox/docs/tmp/html/index.html + git clone https://git.opendaylight.org/gerrit/docs + cd docs + git submodule update --init + tox -edocs + 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 +------------------- + +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. + +For example here is the directory layout on June, 28th 2016:: + + $ tree -L 2 + . + ├── Makefile + ├── conf.py + ├── documentation.rst + ├── getting-started-guide + │ ├── api.rst + │ ├── concepts_and_tools.rst + │ ├── experimental_features.rst + │ ├── index.rst + │ ├── installing_opendaylight.rst + │ ├── introduction.rst + │ ├── karaf_features.rst + │ ├── other_features.rst + │ ├── overview.rst + │ └── who_should_use.rst + ├── index.rst + ├── make.bat + ├── opendaylight-with-openstack + │ ├── images + │ ├── index.rst + │ ├── openstack-with-gbp.rst + │ ├── openstack-with-ovsdb.rst + │ └── openstack-with-vtn.rst + └── submodules + └── releng + └── builder + +The ``getting-started-guide`` and ``opendaylight-with-openstack`` +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:: + + .. toctree:: + :maxdepth: 1 + + getting-started-guide/index + opendaylight-with-openstack/index + submodules/releng/builder/docs/index + +This 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. + +Documentation Layout and Style +------------------------------ + +As mentioned previously we try to follow the python documentation style guide +which defines a few types of sections:: + + # with overline, for parts + * with overline, for chapters + =, for sections + -, for subsections + ^, for subsubsections + ", for paragraphs + +We try to follow 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 +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 +the chapter should use:: + + =, for sections + -, for subsections + ^, for subsubsections + ", for paragraphs + + +Troubleshooting +--------------- + +Make sure you've 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 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 +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 + 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 +an ``ExtensionError`` and can be fixed by deleting the ``.tox`` +directory and building again:: + + rm -rf .tox + tox -edocs + +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. + +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:: + + .. image:: 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 + + + + + +.. _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/