6 The Linux kernel uses `Sphinx`_ to generate pretty documentation from
7 `reStructuredText`_ files under ``Documentation``. To build the documentation in
8 HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated
9 documentation is placed in ``Documentation/output``.
11 .. _Sphinx: http://www.sphinx-doc.org/
12 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
14 The reStructuredText files may contain directives to include structured
15 documentation comments, or kernel-doc comments, from source files. Usually these
16 are used to describe the functions and types and design of the code. The
17 kernel-doc comments have some special structure and formatting, but beyond that
18 they are also treated as reStructuredText.
20 Finally, there are thousands of plain text documentation files scattered around
21 ``Documentation``. Some of these will likely be converted to reStructuredText
22 over time, but the bulk of them will remain in plain text.
29 The ReST markups currently used by the Documentation/ files are meant to be
30 built with ``Sphinx`` version 1.3 or higher. If you desire to build
31 PDF output, it is recommended to use version 1.4.6 or higher.
33 There's a script that checks for the Sphinx requirements. Please see
34 :ref:`sphinx-pre-install` for further details.
36 Most distributions are shipped with Sphinx, but its toolchain is fragile,
37 and it is not uncommon that upgrading it or some other Python packages
38 on your machine would cause the documentation build to break.
40 A way to avoid that is to use a different version than the one shipped
41 with your distributions. In order to do so, it is recommended to install
42 Sphinx inside a virtual environment, using ``virtualenv-3``
43 or ``virtualenv``, depending on how your distribution packaged Python 3.
47 #) Sphinx versions below 1.5 don't work properly with Python's
48 docutils version 0.13.1 or higher. So, if you're willing to use
49 those versions, you should run ``pip install 'docutils==0.12'``.
51 #) It is recommended to use the RTD theme for html output. Depending
52 on the Sphinx version, it should be installed in separate,
53 with ``pip install sphinx_rtd_theme``.
55 #) Some ReST pages contain math expressions. Due to the way Sphinx work,
56 those expressions are written using LaTeX notation. It needs texlive
57 installed with amdfonts and amsmath in order to evaluate them.
59 In summary, if you want to install Sphinx version 1.4.9, you should do::
61 $ virtualenv sphinx_1.4
62 $ . sphinx_1.4/bin/activate
63 (sphinx_1.4) $ pip install -r Documentation/sphinx/requirements.txt
65 After running ``. sphinx_1.4/bin/activate``, the prompt will change,
66 in order to indicate that you're using the new environment. If you
67 open a new shell, you need to rerun this command to enter again at
68 the virtual environment before building the documentation.
73 The kernel documentation build system contains an extension that
74 handles images on both GraphViz and SVG formats (see
75 :ref:`sphinx_kfigure`).
77 For it to work, you need to install both GraphViz and ImageMagick
78 packages. If those packages are not installed, the build system will
79 still build the documentation, but won't include any images at the
85 Such builds are currently supported only with Sphinx versions 1.4 and higher.
87 For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265.
89 Depending on the distribution, you may also need to install a series of
90 ``texlive`` packages that provide the minimal set of functionalities
91 required for ``XeLaTeX`` to work.
93 .. _sphinx-pre-install:
95 Checking for Sphinx dependencies
96 --------------------------------
98 There's a script that automatically check for Sphinx dependencies. If it can
99 recognize your distribution, it will also give a hint about the install
100 command line options for your distro::
102 $ ./scripts/sphinx-pre-install
103 Checking if the needed tools for Fedora release 26 (Twenty Six) are available
104 Warning: better to also install "texlive-luatex85".
107 sudo dnf install -y texlive-luatex85
108 /usr/bin/virtualenv sphinx_1.4
109 . sphinx_1.4/bin/activate
110 pip install -r Documentation/sphinx/requirements.txt
112 Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
114 By default, it checks all the requirements for both html and PDF, including
115 the requirements for images, math expressions and LaTeX build, and assumes
116 that a virtual Python environment will be used. The ones needed for html
117 builds are assumed to be mandatory; the others to be optional.
119 It supports two optional parameters:
122 Disable checks for PDF;
125 Use OS packaging for Sphinx instead of Python virtual environment.
131 The usual way to generate the documentation is to run ``make htmldocs`` or
132 ``make pdfdocs``. There are also other formats available, see the documentation
133 section of ``make help``. The generated documentation is placed in
134 format-specific subdirectories under ``Documentation/output``.
136 To generate documentation, Sphinx (``sphinx-build``) must obviously be
137 installed. For prettier HTML output, the Read the Docs Sphinx theme
138 (``sphinx_rtd_theme``) is used if available. For PDF output you'll also need
139 ``XeLaTeX`` and ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
140 All of these are widely available and packaged in distributions.
142 To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
143 variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
146 To remove the generated documentation, run ``make cleandocs``.
148 Writing Documentation
149 =====================
151 Adding new documentation can be as simple as:
153 1. Add a new ``.rst`` file somewhere under ``Documentation``.
154 2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
156 .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
158 This is usually good enough for simple documentation (like the one you're
159 reading right now), but for larger documents it may be advisable to create a
160 subdirectory (or use an existing one). For example, the graphics subsystem
161 documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
162 and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
165 See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
166 with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
167 to get started with reStructuredText. There are also some `Sphinx specific
170 .. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
171 .. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
173 Specific guidelines for the kernel documentation
174 ------------------------------------------------
176 Here are some specific guidelines for the kernel documentation:
178 * Please don't go overboard with reStructuredText markup. Keep it
179 simple. For the most part the documentation should be plain text with
180 just enough consistency in formatting that it can be converted to
183 * Please keep the formatting changes minimal when converting existing
184 documentation to reStructuredText.
186 * Also update the content, not just the formatting, when converting
189 * Please stick to this order of heading adornments:
191 1. ``=`` with overline for document title::
197 2. ``=`` for chapters::
202 3. ``-`` for sections::
207 4. ``~`` for subsections::
212 Although RST doesn't mandate a specific order ("Rather than imposing a fixed
213 number and order of section title adornment styles, the order enforced will be
214 the order as encountered."), having the higher levels the same overall makes
215 it easier to follow the documents.
217 * For inserting fixed width text blocks (for code examples, use case
218 examples, etc.), use ``::`` for anything that doesn't really benefit
219 from syntax highlighting, especially short snippets. Use
220 ``.. code-block:: <language>`` for longer code blocks that benefit
227 The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a
232 .. c:function:: int ioctl( int fd, int request )
234 The C domain of the kernel-doc has some additional features. E.g. you can
235 *rename* the reference name of a function with a common name like ``open`` or
240 .. c:function:: int ioctl( int fd, int request )
241 :name: VIDIOC_LOG_STATUS
243 The func-name (e.g. ioctl) remains in the output but the ref-name changed from
244 ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
245 changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by:
249 :c:func:`VIDIOC_LOG_STATUS`
255 We recommend the use of *list table* formats. The *list table* formats are
256 double-stage lists. Compared to the ASCII-art they might not be as
258 readers of the text files. Their advantage is that they are easy to
259 create or modify and that the diff of a modification is much more meaningful,
260 because it is limited to the modified content.
262 The ``flat-table`` is a double-stage list similar to the ``list-table`` with
263 some additional features:
265 * column-span: with the role ``cspan`` a cell can be extended through
268 * row-span: with the role ``rspan`` a cell can be extended through
271 * auto span rightmost cell of a table row over the missing cells on the right
272 side of that table-row. With Option ``:fill-cells:`` this behavior can
273 changed from *auto span* to *auto fill*, which automatically inserts (empty)
274 cells instead of spanning the last cell.
278 * ``:header-rows:`` [int] count of header rows
279 * ``:stub-columns:`` [int] count of stub columns
280 * ``:widths:`` [[int] [int] ... ] widths of columns
281 * ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells
285 * ``:cspan:`` [int] additional columns (*morecols*)
286 * ``:rspan:`` [int] additional rows (*morerows*)
288 The example below shows how to use this markup. The first level of the staged
289 list is the *table-row*. In the *table-row* there is only one markup allowed,
290 the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
291 and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
296 .. flat-table:: table title
306 - field 1.2 with autospan
310 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
318 .. flat-table:: table title
328 - field 1.2 with autospan
332 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
343 If you want to add an image, you should use the ``kernel-figure`` and
344 ``kernel-image`` directives. E.g. to insert a figure with a scalable
345 image format use SVG (:ref:`svg_image_example`)::
347 .. kernel-figure:: svg_image.svg
348 :alt: simple SVG image
352 .. _svg_image_example:
354 .. kernel-figure:: svg_image.svg
355 :alt: simple SVG image
359 The kernel figure (and image) directive support **DOT** formated files, see
361 * DOT: http://graphviz.org/pdf/dotguide.pdf
362 * Graphviz: http://www.graphviz.org/content/dot-language
364 A simple example (:ref:`hello_dot_file`)::
366 .. kernel-figure:: hello.dot
369 DOT's hello world example
373 .. kernel-figure:: hello.dot
376 DOT's hello world example
378 Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
379 ``kernel-render`` directives.::
381 .. kernel-render:: DOT
383 :caption: Embedded **DOT** (Graphviz) code
389 How this will be rendered depends on the installed tools. If Graphviz is
390 installed, you will see an vector image. If not the raw markup is inserted as
391 *literal-block* (:ref:`hello_dot_render`).
393 .. _hello_dot_render:
395 .. kernel-render:: DOT
397 :caption: Embedded **DOT** (Graphviz) code
403 The *render* directive has all the options known from the *figure* directive,
404 plus option ``caption``. If ``caption`` has a value, a *figure* node is
405 inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if
406 you want to refer it (:ref:`hello_svg_render`).
410 .. kernel-render:: SVG
411 :caption: Embedded **SVG** markup
414 <?xml version="1.0" encoding="UTF-8"?>
415 <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
419 .. _hello_svg_render:
421 .. kernel-render:: SVG
422 :caption: Embedded **SVG** markup
425 <?xml version="1.0" encoding="UTF-8"?>
426 <svg xmlns="http://www.w3.org/2000/svg"
427 version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
428 <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
429 <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>