Documentation/doc-guide/sphinx.rst

   1 Introduction
   2 ============
   3
   4 The Linux kernel uses `Sphinx`_ to generate pretty documentation from
   5 `reStructuredText`_ files under ``Documentation``. To build the documentation in
   6 HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated
   7 documentation is placed in ``Documentation/output``.
   8
   9 .. _Sphinx: http://www.sphinx-doc.org/
  10 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
  11
  12 The reStructuredText files may contain directives to include structured
  13 documentation comments, or kernel-doc comments, from source files. Usually these
  14 are used to describe the functions and types and design of the code. The
  15 kernel-doc comments have some special structure and formatting, but beyond that
  16 they are also treated as reStructuredText.
  17
  18 Finally, there are thousands of plain text documentation files scattered around
  19 ``Documentation``. Some of these will likely be converted to reStructuredText
  20 over time, but the bulk of them will remain in plain text.
  21
  22 Sphinx Build
  23 ============
  24
  25 The usual way to generate the documentation is to run ``make htmldocs`` or
  26 ``make pdfdocs``. There are also other formats available, see the documentation
  27 section of ``make help``. The generated documentation is placed in
  28 format-specific subdirectories under ``Documentation/output``.
  29
  30 To generate documentation, Sphinx (``sphinx-build``) must obviously be
  31 installed. For prettier HTML output, the Read the Docs Sphinx theme
  32 (``sphinx_rtd_theme``) is used if available. For PDF output you'll also need
  33 ``XeLaTeX`` and ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
  34 All of these are widely available and packaged in distributions.
  35
  36 To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
  37 variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
  38 output.
  39
  40 To remove the generated documentation, run ``make cleandocs``.
  41
  42 Writing Documentation
  43 =====================
  44
  45 Adding new documentation can be as simple as:
  46
  47 1. Add a new ``.rst`` file somewhere under ``Documentation``.
  48 2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
  49
  50 .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
  51
  52 This is usually good enough for simple documentation (like the one you're
  53 reading right now), but for larger documents it may be advisable to create a
  54 subdirectory (or use an existing one). For example, the graphics subsystem
  55 documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
  56 and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
  57 the main index.
  58
  59 See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
  60 with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
  61 to get started with reStructuredText. There are also some `Sphinx specific
  62 markup constructs`_.
  63
  64 .. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
  65 .. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
  66
  67 Specific guidelines for the kernel documentation
  68 ------------------------------------------------
  69
  70 Here are some specific guidelines for the kernel documentation:
  71
  72 * Please don't go overboard with reStructuredText markup. Keep it
  73   simple. For the most part the documentation should be plain text with
  74   just enough consistency in formatting that it can be converted to
  75   other formats.
  76
  77 * Please keep the formatting changes minimal when converting existing
  78   documentation to reStructuredText.
  79
  80 * Also update the content, not just the formatting, when converting
  81   documentation.
  82
  83 * Please stick to this order of heading adornments:
  84
  85   1. ``=`` with overline for document title::
  86
  87        ==============
  88        Document title
  89        ==============
  90
  91   2. ``=`` for chapters::
  92
  93        Chapters
  94        ========
  95
  96   3. ``-`` for sections::
  97
  98        Section
  99        -------
 100
 101   4. ``~`` for subsections::
 102
 103        Subsection
 104        ~~~~~~~~~~
 105
 106   Although RST doesn't mandate a specific order ("Rather than imposing a fixed
 107   number and order of section title adornment styles, the order enforced will be
 108   the order as encountered."), having the higher levels the same overall makes
 109   it easier to follow the documents.
 110
 111 * For inserting fixed width text blocks (for code examples, use case
 112   examples, etc.), use ``::`` for anything that doesn't really benefit
 113   from syntax highlighting, especially short snippets. Use
 114   ``.. code-block:: <language>`` for longer code blocks that benefit
 115   from highlighting.
 116
 117
 118 the C domain
 119 ------------
 120
 121 The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a
 122 function prototype:
 123
 124 .. code-block:: rst
 125
 126     .. c:function:: int ioctl( int fd, int request )
 127
 128 The C domain of the kernel-doc has some additional features. E.g. you can
 129 *rename* the reference name of a function with a common name like ``open`` or
 130 ``ioctl``:
 131
 132 .. code-block:: rst
 133
 134      .. c:function:: int ioctl( int fd, int request )
 135         :name: VIDIOC_LOG_STATUS
 136
 137 The func-name (e.g. ioctl) remains in the output but the ref-name changed from
 138 ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
 139 changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by:
 140
 141 .. code-block:: rst
 142
 143      :c:func:`VIDIOC_LOG_STATUS`
 144
 145
 146 list tables
 147 -----------
 148
 149 We recommend the use of *list table* formats. The *list table* formats are
 150 double-stage lists. Compared to the ASCII-art they might not be as
 151 comfortable for
 152 readers of the text files. Their advantage is that they are easy to
 153 create or modify and that the diff of a modification is much more meaningful,
 154 because it is limited to the modified content.
 155
 156 The ``flat-table`` is a double-stage list similar to the ``list-table`` with
 157 some additional features:
 158
 159 * column-span: with the role ``cspan`` a cell can be extended through
 160   additional columns
 161
 162 * row-span: with the role ``rspan`` a cell can be extended through
 163   additional rows
 164
 165 * auto span rightmost cell of a table row over the missing cells on the right
 166   side of that table-row.  With Option ``:fill-cells:`` this behavior can
 167   changed from *auto span* to *auto fill*, which automatically inserts (empty)
 168   cells instead of spanning the last cell.
 169
 170 options:
 171
 172 * ``:header-rows:``   [int] count of header rows
 173 * ``:stub-columns:``  [int] count of stub columns
 174 * ``:widths:``        [[int] [int] ... ] widths of columns
 175 * ``:fill-cells:``    instead of auto-spanning missing cells, insert missing cells
 176
 177 roles:
 178
 179 * ``:cspan:`` [int] additional columns (*morecols*)
 180 * ``:rspan:`` [int] additional rows (*morerows*)
 181
 182 The example below shows how to use this markup.  The first level of the staged
 183 list is the *table-row*. In the *table-row* there is only one markup allowed,
 184 the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
 185 and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
 186 <last row>`).
 187
 188 .. code-block:: rst
 189
 190    .. flat-table:: table title
 191       :widths: 2 1 1 3
 192
 193       * - head col 1
 194         - head col 2
 195         - head col 3
 196         - head col 4
 197
 198       * - column 1
 199         - field 1.1
 200         - field 1.2 with autospan
 201
 202       * - column 2
 203         - field 2.1
 204         - :rspan:`1` :cspan:`1` field 2.2 - 3.3
 205
 206       * .. _`last row`:
 207
 208         - column 3
 209
 210 Rendered as:
 211
 212    .. flat-table:: table title
 213       :widths: 2 1 1 3
 214
 215       * - head col 1
 216         - head col 2
 217         - head col 3
 218         - head col 4
 219
 220       * - column 1
 221         - field 1.1
 222         - field 1.2 with autospan
 223
 224       * - column 2
 225         - field 2.1
 226         - :rspan:`1` :cspan:`1` field 2.2 - 3.3
 227
 228       * .. _`last row`:
 229
 230         - column 3
 231
 232
 233 Figures & Images
 234 ================
 235
 236 If you want to add an image, you should use the ``kernel-figure`` and
 237 ``kernel-image`` directives. E.g. to insert a figure with a scalable
 238 image format use SVG (:ref:`svg_image_example`)::
 239
 240     .. kernel-figure::  svg_image.svg
 241        :alt:    simple SVG image
 242
 243        SVG image example
 244
 245 .. _svg_image_example:
 246
 247 .. kernel-figure::  svg_image.svg
 248    :alt:    simple SVG image
 249
 250    SVG image example
 251
 252 The kernel figure (and image) directive support **DOT** formated files, see
 253
 254 * DOT: http://graphviz.org/pdf/dotguide.pdf
 255 * Graphviz: http://www.graphviz.org/content/dot-language
 256
 257 A simple example (:ref:`hello_dot_file`)::
 258
 259   .. kernel-figure::  hello.dot
 260      :alt:    hello world
 261
 262      DOT's hello world example
 263
 264 .. _hello_dot_file:
 265
 266 .. kernel-figure::  hello.dot
 267    :alt:    hello world
 268
 269    DOT's hello world example
 270
 271 Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
 272 ``kernel-render`` directives.::
 273
 274   .. kernel-render:: DOT
 275      :alt: foobar digraph
 276      :caption: Embedded **DOT** (Graphviz) code
 277
 278      digraph foo {
 279       "bar" -> "baz";
 280      }
 281
 282 How this will be rendered depends on the installed tools. If Graphviz is
 283 installed, you will see an vector image. If not the raw markup is inserted as
 284 *literal-block* (:ref:`hello_dot_render`).
 285
 286 .. _hello_dot_render:
 287
 288 .. kernel-render:: DOT
 289    :alt: foobar digraph
 290    :caption: Embedded **DOT** (Graphviz) code
 291
 292    digraph foo {
 293       "bar" -> "baz";
 294    }
 295
 296 The *render* directive has all the options known from the *figure* directive,
 297 plus option ``caption``.  If ``caption`` has a value, a *figure* node is
 298 inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if
 299 you want to refer it (:ref:`hello_svg_render`).
 300
 301 Embedded **SVG**::
 302
 303   .. kernel-render:: SVG
 304      :caption: Embedded **SVG** markup
 305      :alt: so-nw-arrow
 306
 307      <?xml version="1.0" encoding="UTF-8"?>
 308      <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
 309         ...
 310      </svg>
 311
 312 .. _hello_svg_render:
 313
 314 .. kernel-render:: SVG
 315    :caption: Embedded **SVG** markup
 316    :alt: so-nw-arrow
 317
 318    <?xml version="1.0" encoding="UTF-8"?>
 319    <svg xmlns="http://www.w3.org/2000/svg"
 320      version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
 321    <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
 322    <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
 323    </svg>