docs/documentation.rst

   1 .. _documentation-guide:
   2
   3 ###################
   4 Documentation Guide
   5 ###################
   6
   7 This guide provides details on how to contribute to the OpenDaylight
   8 documentation. OpenDaylight currently uses a mix of AsciiDoc_ and
   9 reStructuredText_ for documentation, although the `Documentation
  10 Group`_ is generally trying to move toward using reStructuredText_ and
  11 Sphinx_ to build it as it is widely-used to provide both HTML and pdf
  12 documentation that can be easily versioned alongside the code. It also
  13 offers similar syntax to Markdown which is familiar to large numbers of
  14 people.
  15
  16 reStructuredText-based Documentation
  17 ====================================
  18
  19 When using reStructuredText, we try to follow the python documentation
  20 style guide. See: https://docs.python.org/devguide/documenting.html
  21
  22 To build and review the reStructuredText documentation locally you must
  23 have installed locally:
  24
  25 * python
  26 * python-tox
  27
  28 Which both should be available in most distribution's package managers.
  29
  30 Then simply run tox and open the html produced via your favorite web
  31 browser as follows:
  32
  33 .. code-block:: bash
  34
  35    git clone https://git.opendaylight.org/gerrit/docs
  36    cd docs
  37    git submodule update --init
  38    tox -edocs
  39    firefox docs/_build/html/index.html
  40
  41 .. note:: Make sure to run `tox -edocs` and not just `tox`. See `Make
  42           sure you run tox -edocs`_
  43
  44 Directory Structure
  45 -------------------
  46
  47 The directory structure for the reStructuredText documentation is
  48 rooted in the ``docs`` directory inside the ``docs`` ``git``
  49 repository.
  50
  51 Below that there are guides hosted directly in the ``docs`` ``git``
  52 repository and there are guides hosted in remote ``git`` repositories.
  53 Usually those are for project-specific information.
  54
  55 For example here is the directory layout on June, 28th 2016::
  56
  57    $ tree -L 2
  58    .
  59    ├── Makefile
  60    ├── conf.py
  61    ├── documentation.rst
  62    ├── getting-started-guide
  63    │   ├── api.rst
  64    │   ├── concepts_and_tools.rst
  65    │   ├── experimental_features.rst
  66    │   ├── index.rst
  67    │   ├── installing_opendaylight.rst
  68    │   ├── introduction.rst
  69    │   ├── karaf_features.rst
  70    │   ├── other_features.rst
  71    │   ├── overview.rst
  72    │   └── who_should_use.rst
  73    ├── index.rst
  74    ├── make.bat
  75    ├── opendaylight-with-openstack
  76    │   ├── images
  77    │   ├── index.rst
  78    │   ├── openstack-with-gbp.rst
  79    │   ├── openstack-with-ovsdb.rst
  80    │   └── openstack-with-vtn.rst
  81    └── submodules
  82        └── releng
  83            └── builder
  84
  85 The ``getting-started-guide`` and ``opendaylight-with-openstack``
  86 directories correspond to two guides hosted in the ``docs`` repository,
  87 while the ``submodules/releng/builder`` directory houses documentation
  88 for the `RelEng/Builder`_ project.
  89
  90 Inside each guide there is usually an ``index.rst`` file which then
  91 includes other files using a ``toctree`` directive. For example::
  92
  93    .. toctree::
  94       :maxdepth: 1
  95
  96       getting-started-guide/index
  97       opendaylight-with-openstack/index
  98       submodules/releng/builder/docs/index
  99
 100 This creates a table of contents on that page where each heading of the
 101 table of contents is the root of the files that are included.
 102
 103 .. note:: When including rst files using ``toctree`` omit the .rst at
 104           the end of the file name.
 105
 106 Documentation Layout and Style
 107 ------------------------------
 108
 109 As mentioned previously we try to follow the python documentation style guide
 110 which defines a few types of sections::
 111
 112     # with overline, for parts
 113     * with overline, for chapters
 114     =, for sections
 115     -, for subsections
 116     ^, for subsubsections
 117     ", for paragraphs
 118
 119 We try to follow the following structure based on that recommendation::
 120
 121     docs/index.rst                 -> entry point
 122     docs/____-guide/index.rst      -> part
 123     docs/____-guide/<chapter>.rst  -> chapter
 124
 125 In the ____-guide/index.rst we use the # with overline at the very top
 126 of the file to determine that it is a part and then within each chapter
 127 file we start the document with a section using * with overline to
 128 denote that it's the chapter heading and then everything in the rest of
 129 the chapter should use::
 130
 131     =, for sections
 132     -, for subsections
 133     ^, for subsubsections
 134     ", for paragraphs
 135
 136
 137 Troubleshooting
 138 ---------------
 139
 140 Make sure you've cloned submodules
 141 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 142
 143 If you see an error like this::
 144
 145    ./build-integration-robot-libdoc.sh: line 6: cd: submodules/integration/test/csit/libraries: No such file or directory
 146    Resource file '*.robot' does not exist.
 147
 148 It means that you haven't pulled down the git submodule for the integration/test project. The fastest way to do that is::
 149
 150    git submodule update --init
 151
 152 In some cases, you might wind up with submodules which are somehow
 153 out-of-sync and in that case, the easiest way to fix it is delete the
 154 submodules directory and then re-clone the submodules::
 155
 156    rm -rf docs/submodules/
 157    git submodule update --init
 158
 159 .. warning:: This will delete any local changes or information you made
 160              in the submodules. This should only be the case if you
 161              manually edited files in that directory.
 162
 163 Make sure you run tox -edocs
 164 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 165
 166 If you see an error like::
 167
 168    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)
 169    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)
 170
 171 It usually means you ran `tox` and not `tox -edocs`, which will result
 172 in running jobs inside submodules which aren't supported by the
 173 environment defined by the `requirements.txt` file in the documentation
 174 tox setup. Just run tox -edocs and it should be fine.
 175
 176 Clear your tox directory and try again
 177 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 178
 179 Sometimes, tox will not detect when your ``requirements.txt`` file has
 180 changed and so will try to run things without the correct dependencies.
 181 This usually manifests as ``No module named X`` errors or
 182 an ``ExtensionError`` and can be fixed by deleting the ``.tox``
 183 directory and building again::
 184
 185    rm -rf .tox
 186    tox -edocs
 187
 188 AsciiDoc-based Documentation
 189 ============================
 190
 191 Information on the AsciiDoc tools and build system can be found here:
 192 https://wiki.opendaylight.org/view/Documentation/Tools
 193
 194 Directory Structure
 195 -------------------
 196
 197 The AsciiDoc documentation is all located in the ``manuals`` directory
 198 of the ``docs`` ``git`` repository. An example of the directory
 199 structure on June 28th, 2016 can be seen here::
 200
 201    $ tree -L 4
 202    .
 203    ├── common
 204    │   └── app_support.xml
 205    ├── developer-guide
 206    │   ├── pom.xml
 207    │   └── src
 208    │       └── main
 209    │           ├── asciidoc
 210    │           └── resources
 211    ├── getting-started-guide
 212    │   ├── pom.xml
 213    │   └── src
 214    │       └── main
 215    │           ├── asciidoc
 216    │           └── resources
 217    ├── howto-openstack
 218    │   ├── pom.xml
 219    │   └── src
 220    │       └── main
 221    │           ├── asciidoc
 222    │           └── resources
 223    ├── pom.xml
 224    ├── readme
 225    │   ├── pom.xml
 226    │   └── src
 227    │       └── main
 228    │           └── asciidoc
 229    └── user-guide
 230        ├── pom.xml
 231        └── src
 232            └── main
 233                ├── asciidoc
 234                └── resources
 235
 236 Each of the top-level directories under ``manuals`` is a whole guide by
 237 itself and it contains a ``pom.xml`` file saying how to build it, a
 238 ``src/main/asciidoc`` directory with AsciiDoc source files and a
 239 ``src/main/resources`` directory containing images.
 240
 241 Migration from AsciiDoc to ReStructuredText
 242 ===========================================
 243
 244 Automatically
 245 -------------
 246
 247 In theory, Pandoc_ can convert from DocBook to reStructuredText and we
 248 produce DocBook as part of our build chain from AsciiDoctor. In
 249 practice, for modest-sized migrations doing things by hand works fairly
 250 well.
 251
 252 By Hand
 253 -------
 254
 255 Converting from AsciiDoc to reStructuredText is usually pretty
 256 straightforward and involves looking up the basic syntax for what you
 257 want to do by looking it up in the reStructuredText_ guide.
 258
 259 The differences are usually minor and fast to change.
 260
 261 Also, because of how fast Sphinx builds, and how fast it is to refresh
 262 the HTML documentation rapid iteration is very easy.
 263
 264 Bold/Italics/Verbatim Formatting
 265 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 266
 267 This is mostly minor syntax issues. In AsciiDoc you do inline
 268 formatting something like this::
 269
 270    *bold* _italic_ +verbatim+ `verbatim`
 271
 272 In reStructuredText, things are slightly different::
 273
 274    **bold** *italic* ``verbatim``
 275
 276 Images
 277 ^^^^^^
 278
 279 Image formats change from something like::
 280
 281    .OpenStack Architecture
 282    image::vtn/OpenStackDeveloperGuide.png["OpenStack Architecture",width=500]
 283
 284 To something like::
 285
 286    .. image:: images/dlux-default.png
 287
 288 A helpful regular expression for automating the replacements is something like::
 289
 290    search: ^( *)\.(.+)\n +image::(.+)\[(.+),width=(\d+)\]
 291    replace: $1.. figure:: images/dlux/$3\n$1   :width: $5\n\n$1   $2
 292
 293
 294
 295
 296
 297 .. _AsciiDoc: http://www.methods.co.nz/asciidoc/
 298 .. _Sphinx: http://www.sphinx-doc.org/en/stable/
 299 .. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html
 300 .. _Documentation Group: https://wiki.opendaylight.org/view/Documentation/
 301 .. _RelEng/Builder: https://wiki.opendaylight.org/view/RelEng/Builder
 302 .. _Pandoc: http://pandoc.org/