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:
  21
  22     https://docs.python.org/devguide/documenting.html
  23
  24 To build and review the reStructuredText documentation locally you must
  25 have installed locally:
  26
  27 * python
  28 * python-tox
  29
  30 Which both should be available in most distribution's package managers.
  31
  32 Then simply run tox and open the html produced via your favourite web
  33 browser as follows:
  34
  35 .. code-block:: bash
  36
  37     tox -edocs
  38     firefox docs/_build/html/index.html
  39
  40 Directory Structure
  41 -------------------
  42
  43 The directory structure for the reStructuredText documentation is
  44 rooted in the ``docs`` directory inside the ``docs`` ``git``
  45 repository.
  46
  47 Below that there are guides hosted directly in the ``docs`` ``git``
  48 repository and there are guides hosted in remote ``git`` repositories.
  49 Usually those are for project-specific information.
  50
  51 For example here is the directory layout on June, 28th 2016::
  52
  53    $ tree -L 2
  54    .
  55    ├── Makefile
  56    ├── conf.py
  57    ├── documentation.rst
  58    ├── getting-started-guide
  59    │   ├── api.rst
  60    │   ├── concepts_and_tools.rst
  61    │   ├── experimental_features.rst
  62    │   ├── index.rst
  63    │   ├── installing_opendaylight.rst
  64    │   ├── introduction.rst
  65    │   ├── karaf_features.rst
  66    │   ├── other_features.rst
  67    │   ├── overview.rst
  68    │   └── who_should_use.rst
  69    ├── index.rst
  70    ├── make.bat
  71    ├── opendaylight-with-openstack
  72    │   ├── images
  73    │   ├── index.rst
  74    │   ├── openstack-with-gbp.rst
  75    │   ├── openstack-with-ovsdb.rst
  76    │   └── openstack-with-vtn.rst
  77    └── submodules
  78        └── releng
  79            └── builder
  80
  81 The ``getting-started-guide`` and ``opendaylight-with-openstack``
  82 directories correspond to two guides hosted in the ``docs`` repository,
  83 while the ``submodules/releng/builder`` directory houses documentation
  84 for the `RelEng/Builder`_ project.
  85
  86 Inside each guide there is usually an ``index.rst`` file which then
  87 includes other files using a ``toctree`` directive. For example::
  88
  89    .. toctree::
  90       :maxdepth: 1
  91
  92       getting-started-guide/index
  93       opendaylight-with-openstack/index
  94       submodules/releng/builder/docs/index
  95
  96 This creates a table of contents on that page where each heading of the
  97 table of contents is the root of the files that are included.
  98
  99 .. note:: When including rst files using ``toctree`` omit the .rst at
 100           the end of the file name.
 101
 102 Documentation Layout and Style
 103 ------------------------------
 104
 105 As mentioned previously we try to follow the python documentation style guide
 106 which defines a few types of sections::
 107
 108     # with overline, for parts
 109     * with overline, for chapters
 110     =, for sections
 111     -, for subsections
 112     ^, for subsubsections
 113     ", for paragraphs
 114
 115 We try to follow the following structure based on that recommendation::
 116
 117     docs/index.rst                 -> entry point
 118     docs/____-guide/index.rst      -> part
 119     docs/____-guide/<chapter>.rst  -> chapter
 120
 121 In the ____-guide/index.rst we use the # with overline at the very top
 122 of the file to determine that it is a part and then within each chapter
 123 file we start the document with a section using * with overline to
 124 denote that it's the chapter heading and then everything in the rest of
 125 the chapter should use::
 126
 127     =, for sections
 128     -, for subsections
 129     ^, for subsubsections
 130     ", for paragraphs
 131
 132
 133 Troubleshooting
 134 ---------------
 135
 136 If you see an error like this::
 137
 138    ./build-integration-robot-libdoc.sh: line 6: cd: submodules/integration/test/csit/libraries: No such file or directory
 139    Resource file '*.robot' does not exist.
 140
 141 It means that you haven't pulled down the git submodule for the integration/test project. The fastest way to do that is::
 142
 143    git submodule init
 144    git submodule update
 145
 146 Also, you may notice errors like these when building::
 147
 148    Importing test library '/Users/ckd/git-reps/docs/docs/submodules/integration/test/csit/libraries/AAAJsonUtils.py' failed: ImportError: No module named jsonpath
 149
 150    sed: 1: "SxpLib.robot.html": invalid command code S
 151
 152 They can be ignored. This is an artifact of our building documentation for the robot test framework customizations OpenDaylight has and is being tracked as `BUG-6159 <https://bugs.opendaylight.org/show_bug.cgi?id=6159>`_. More information can be found there.
 153
 154 AsciiDoc-based Documentation
 155 ============================
 156
 157 Information on the AsciiDoc tools and build system can be found here:
 158
 159    https://wiki.opendaylight.org/view/Documentation/Tools
 160
 161 Directory Structure
 162 -------------------
 163
 164 The AsciiDoc documentation is all located in the ``manuals`` directory
 165 of the ``docs`` ``git`` repository. An example of the directory
 166 structure on June 28th, 2016 can be seen here::
 167
 168    $ tree -L 4
 169    .
 170    ├── common
 171    │   └── app_support.xml
 172    ├── developer-guide
 173    │   ├── pom.xml
 174    │   └── src
 175    │       └── main
 176    │           ├── asciidoc
 177    │           └── resources
 178    ├── getting-started-guide
 179    │   ├── pom.xml
 180    │   └── src
 181    │       └── main
 182    │           ├── asciidoc
 183    │           └── resources
 184    ├── howto-openstack
 185    │   ├── pom.xml
 186    │   └── src
 187    │       └── main
 188    │           ├── asciidoc
 189    │           └── resources
 190    ├── pom.xml
 191    ├── readme
 192    │   ├── pom.xml
 193    │   └── src
 194    │       └── main
 195    │           └── asciidoc
 196    └── user-guide
 197        ├── pom.xml
 198        └── src
 199            └── main
 200                ├── asciidoc
 201                └── resources
 202
 203 Each of the top-level directories under ``manuals`` is a whole guide by
 204 itself and it contains a ``pom.xml`` file saying how to build it, a
 205 ``src/main/asciidoc`` directory with AsciiDoc source files and a
 206 ``src/main/resources`` directory containing images.
 207
 208 Migration from AsciiDoc to ReStructuredText
 209 ===========================================
 210
 211 Automatically
 212 -------------
 213
 214 In theory, Pandoc_ can convert from DocBook to reStructuredText and we
 215 produce DocBook as part of our build chain from AsciiDoctor. In
 216 practice, for modest-sized migrations doing things by hand works fairly
 217 well.
 218
 219 By Hand
 220 -------
 221
 222 Converting from AsciiDoc to reStructuredText is usually pretty
 223 straightforward and involves looking up the basic syntax for what you
 224 want to do by looking it up in the reStructuredText_ guide.
 225
 226 The differences are usually minor and fast to change.
 227
 228 Also, because of how fast Sphinx builds, and how fast it is to refresh
 229 the HTML documentation rapid iteration is very easy.
 230
 231 Bold/Italics/Verbatim Formatting
 232 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 233
 234 This is mostly minor syntax issues. In AsciiDoc you do inline
 235 formatting something like this::
 236
 237    *bold* _italic_ +verbatim+ `verbatim`
 238
 239 In reStructuredText, things are slightly different::
 240
 241    **bold** *italic* ``verbatim``
 242
 243 Images
 244 ^^^^^^
 245
 246 Image formats change from something like::
 247
 248    .OpenStack Architecture
 249    image::vtn/OpenStackDeveloperGuide.png["OpenStack Architecture",width=500]
 250
 251 To something like::
 252
 253    .. image:: images/dlux-default.png
 254
 255 A helpful regular expression for automating the replacements is something like::
 256
 257    search: ^( *)\.(.+)\n +image::(.+)\[(.+),width=(\d+)\]
 258    replace: $1.. figure:: images/dlux/$3\n$1   :width: $5\n\n$1   $2
 259
 260
 261
 262
 263
 264 .. _AsciiDoc: http://www.methods.co.nz/asciidoc/
 265 .. _Sphinx: http://www.sphinx-doc.org/en/stable/
 266 .. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html
 267 .. _Documentation Group: https://wiki.opendaylight.org/view/Documentation/
 268 .. _RelEng/Builder: https://wiki.opendaylight.org/view/RelEng/Builder
 269 .. _Pandoc: http://pandoc.org/