3 =====================================
4 Using Sphinx for kernel documentation
5 =====================================
7 The Linux kernel uses `Sphinx`_ to generate pretty documentation from
8 `reStructuredText`_ files under ``Documentation``. To build the documentation in
9 HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated
10 documentation is placed in ``Documentation/output``.
12 .. _Sphinx: http://www.sphinx-doc.org/
13 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
15 The reStructuredText files may contain directives to include structured
16 documentation comments, or kernel-doc comments, from source files. Usually these
17 are used to describe the functions and types and design of the code. The
18 kernel-doc comments have some special structure and formatting, but beyond that
19 they are also treated as reStructuredText.
21 Finally, there are thousands of plain text documentation files scattered around
22 ``Documentation``. Some of these will likely be converted to reStructuredText
23 over time, but the bulk of them will remain in plain text.
30 The ReST markups currently used by the Documentation/ files are meant to be
31 built with ``Sphinx`` version 1.7 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 #) It is recommended to use the RTD theme for html output. Depending
48 on the Sphinx version, it should be installed separately,
49 with ``pip install sphinx_rtd_theme``.
51 #) Some ReST pages contain math expressions. Due to the way Sphinx works,
52 those expressions are written using LaTeX notation. It needs texlive
53 installed with amsfonts and amsmath in order to evaluate them.
55 In summary, if you want to install Sphinx version 2.4.4, you should do::
57 $ virtualenv sphinx_2.4.4
58 $ . sphinx_2.4.4/bin/activate
59 (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
61 After running ``. sphinx_2.4.4/bin/activate``, the prompt will change,
62 in order to indicate that you're using the new environment. If you
63 open a new shell, you need to rerun this command to enter again at
64 the virtual environment before building the documentation.
69 The kernel documentation build system contains an extension that
70 handles images on both GraphViz and SVG formats (see
71 :ref:`sphinx_kfigure`).
73 For it to work, you need to install both GraphViz and ImageMagick
74 packages. If those packages are not installed, the build system will
75 still build the documentation, but won't include any images at the
81 Such builds are currently supported only with Sphinx versions 2.4 and higher.
83 For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265.
85 Depending on the distribution, you may also need to install a series of
86 ``texlive`` packages that provide the minimal set of functionalities
87 required for ``XeLaTeX`` to work.
89 .. _sphinx-pre-install:
91 Checking for Sphinx dependencies
92 --------------------------------
94 There's a script that automatically check for Sphinx dependencies. If it can
95 recognize your distribution, it will also give a hint about the install
96 command line options for your distro::
98 $ ./scripts/sphinx-pre-install
99 Checking if the needed tools for Fedora release 26 (Twenty Six) are available
100 Warning: better to also install "texlive-luatex85".
103 sudo dnf install -y texlive-luatex85
104 /usr/bin/virtualenv sphinx_2.4.4
105 . sphinx_2.4.4/bin/activate
106 pip install -r Documentation/sphinx/requirements.txt
108 Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
110 By default, it checks all the requirements for both html and PDF, including
111 the requirements for images, math expressions and LaTeX build, and assumes
112 that a virtual Python environment will be used. The ones needed for html
113 builds are assumed to be mandatory; the others to be optional.
115 It supports two optional parameters:
118 Disable checks for PDF;
121 Use OS packaging for Sphinx instead of Python virtual environment.
127 The usual way to generate the documentation is to run ``make htmldocs`` or
128 ``make pdfdocs``. There are also other formats available: see the documentation
129 section of ``make help``. The generated documentation is placed in
130 format-specific subdirectories under ``Documentation/output``.
132 To generate documentation, Sphinx (``sphinx-build``) must obviously be
133 installed. For prettier HTML output, the Read the Docs Sphinx theme
134 (``sphinx_rtd_theme``) is used if available. For PDF output you'll also need
135 ``XeLaTeX`` and ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
136 All of these are widely available and packaged in distributions.
138 To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
139 variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
142 It is also possible to pass an extra DOCS_CSS overlay file, in order to customize
143 the html layout, by using the ``DOCS_CSS`` make variable.
145 By default, the build will try to use the Read the Docs sphinx theme:
147 https://github.com/readthedocs/sphinx_rtd_theme
149 If the theme is not available, it will fall-back to the classic one.
151 The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
153 To remove the generated documentation, run ``make cleandocs``.
155 Writing Documentation
156 =====================
158 Adding new documentation can be as simple as:
160 1. Add a new ``.rst`` file somewhere under ``Documentation``.
161 2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
163 .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
165 This is usually good enough for simple documentation (like the one you're
166 reading right now), but for larger documents it may be advisable to create a
167 subdirectory (or use an existing one). For example, the graphics subsystem
168 documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
169 and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
172 See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
173 with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
174 to get started with reStructuredText. There are also some `Sphinx specific
177 .. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
178 .. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
180 Specific guidelines for the kernel documentation
181 ------------------------------------------------
183 Here are some specific guidelines for the kernel documentation:
185 * Please don't go overboard with reStructuredText markup. Keep it
186 simple. For the most part the documentation should be plain text with
187 just enough consistency in formatting that it can be converted to
190 * Please keep the formatting changes minimal when converting existing
191 documentation to reStructuredText.
193 * Also update the content, not just the formatting, when converting
196 * Please stick to this order of heading adornments:
198 1. ``=`` with overline for document title::
204 2. ``=`` for chapters::
209 3. ``-`` for sections::
214 4. ``~`` for subsections::
219 Although RST doesn't mandate a specific order ("Rather than imposing a fixed
220 number and order of section title adornment styles, the order enforced will be
221 the order as encountered."), having the higher levels the same overall makes
222 it easier to follow the documents.
224 * For inserting fixed width text blocks (for code examples, use case
225 examples, etc.), use ``::`` for anything that doesn't really benefit
226 from syntax highlighting, especially short snippets. Use
227 ``.. code-block:: <language>`` for longer code blocks that benefit
228 from highlighting. For a short snippet of code embedded in the text, use \`\`.
234 The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a
239 .. c:function:: int ioctl( int fd, int request )
241 The C domain of the kernel-doc has some additional features. E.g. you can
242 *rename* the reference name of a function with a common name like ``open`` or
247 .. c:function:: int ioctl( int fd, int request )
248 :name: VIDIOC_LOG_STATUS
250 The func-name (e.g. ioctl) remains in the output but the ref-name changed from
251 ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
252 changed to ``VIDIOC_LOG_STATUS``.
254 Please note that there is no need to use ``c:func:`` to generate cross
255 references to function documentation. Due to some Sphinx extension magic,
256 the documentation build system will automatically turn a reference to
257 ``function()`` into a cross reference if an index entry for the given
258 function name exists. If you see ``c:func:`` use in a kernel document,
259 please feel free to remove it.
265 The list-table formats can be useful for tables that are not easily laid
266 out in the usual Sphinx ASCII-art formats. These formats are nearly
267 impossible for readers of the plain-text documents to understand, though,
268 and should be avoided in the absence of a strong justification for their
271 The ``flat-table`` is a double-stage list similar to the ``list-table`` with
272 some additional features:
274 * column-span: with the role ``cspan`` a cell can be extended through
277 * row-span: with the role ``rspan`` a cell can be extended through
280 * auto span rightmost cell of a table row over the missing cells on the right
281 side of that table-row. With Option ``:fill-cells:`` this behavior can
282 changed from *auto span* to *auto fill*, which automatically inserts (empty)
283 cells instead of spanning the last cell.
287 * ``:header-rows:`` [int] count of header rows
288 * ``:stub-columns:`` [int] count of stub columns
289 * ``:widths:`` [[int] [int] ... ] widths of columns
290 * ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells
294 * ``:cspan:`` [int] additional columns (*morecols*)
295 * ``:rspan:`` [int] additional rows (*morerows*)
297 The example below shows how to use this markup. The first level of the staged
298 list is the *table-row*. In the *table-row* there is only one markup allowed,
299 the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
300 and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
305 .. flat-table:: table title
315 - field 1.2 with autospan
319 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
327 .. flat-table:: table title
337 - field 1.2 with autospan
341 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
350 Cross-referencing from one documentation page to another can be done simply by
351 writing the path to the document file, no special syntax required. The path can
352 be either absolute or relative. For absolute paths, start it with
353 "Documentation/". For example, to cross-reference to this page, all the
354 following are valid options, depending on the current document's directory (note
355 that the ``.rst`` extension is required)::
357 See Documentation/doc-guide/sphinx.rst. This always works.
358 Take a look at sphinx.rst, which is at this same directory.
359 Read ../sphinx.rst, which is one directory above.
361 If you want the link to have a different rendered text other than the document's
362 title, you need to use Sphinx's ``doc`` role. For example::
364 See :doc:`my custom link text for document sphinx <sphinx>`.
366 For most use cases, the former is preferred, as it is cleaner and more suited
367 for people reading the source files. If you come across a ``:doc:`` usage that
368 isn't adding any value, please feel free to convert it to just the document
371 For information on cross-referencing to kernel-doc functions or types, see
372 Documentation/doc-guide/kernel-doc.rst.
379 If you want to add an image, you should use the ``kernel-figure`` and
380 ``kernel-image`` directives. E.g. to insert a figure with a scalable
381 image format, use SVG (:ref:`svg_image_example`)::
383 .. kernel-figure:: svg_image.svg
384 :alt: simple SVG image
388 .. _svg_image_example:
390 .. kernel-figure:: svg_image.svg
391 :alt: simple SVG image
395 The kernel figure (and image) directive supports **DOT** formatted files, see
397 * DOT: http://graphviz.org/pdf/dotguide.pdf
398 * Graphviz: http://www.graphviz.org/content/dot-language
400 A simple example (:ref:`hello_dot_file`)::
402 .. kernel-figure:: hello.dot
405 DOT's hello world example
409 .. kernel-figure:: hello.dot
412 DOT's hello world example
414 Embedded *render* markups (or languages) like Graphviz's **DOT** are provided by the
415 ``kernel-render`` directives.::
417 .. kernel-render:: DOT
419 :caption: Embedded **DOT** (Graphviz) code
425 How this will be rendered depends on the installed tools. If Graphviz is
426 installed, you will see a vector image. If not, the raw markup is inserted as
427 *literal-block* (:ref:`hello_dot_render`).
429 .. _hello_dot_render:
431 .. kernel-render:: DOT
433 :caption: Embedded **DOT** (Graphviz) code
439 The *render* directive has all the options known from the *figure* directive,
440 plus option ``caption``. If ``caption`` has a value, a *figure* node is
441 inserted. If not, an *image* node is inserted. A ``caption`` is also needed, if
442 you want to refer to it (:ref:`hello_svg_render`).
446 .. kernel-render:: SVG
447 :caption: Embedded **SVG** markup
450 <?xml version="1.0" encoding="UTF-8"?>
451 <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
455 .. _hello_svg_render:
457 .. kernel-render:: SVG
458 :caption: Embedded **SVG** markup
461 <?xml version="1.0" encoding="UTF-8"?>
462 <svg xmlns="http://www.w3.org/2000/svg"
463 version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
464 <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
465 <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>