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
136 (https://www.imagemagick.org).\ [#ink]_
137 All of these are widely available and packaged in distributions.
139 To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
140 variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
143 It is also possible to pass an extra DOCS_CSS overlay file, in order to customize
144 the html layout, by using the ``DOCS_CSS`` make variable.
146 By default, the build will try to use the Read the Docs sphinx theme:
148 https://github.com/readthedocs/sphinx_rtd_theme
150 If the theme is not available, it will fall-back to the classic one.
152 The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
154 There is another make variable ``SPHINXDIRS``, which is useful when test
155 building a subset of documentation. For example, you can build documents
156 under ``Documentation/doc-guide`` by running
157 ``make SPHINXDIRS=doc-guide htmldocs``.
158 The documentation section of ``make help`` will show you the list of
159 subdirectories you can specify.
161 To remove the generated documentation, run ``make cleandocs``.
163 .. [#ink] Having ``inkscape(1)`` from Inkscape (https://inkscape.org)
164 as well would improve the quality of images embedded in PDF
165 documents, especially for kernel releases 5.18 and later.
167 Writing Documentation
168 =====================
170 Adding new documentation can be as simple as:
172 1. Add a new ``.rst`` file somewhere under ``Documentation``.
173 2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
175 .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
177 This is usually good enough for simple documentation (like the one you're
178 reading right now), but for larger documents it may be advisable to create a
179 subdirectory (or use an existing one). For example, the graphics subsystem
180 documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
181 and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
184 See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
185 with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
186 to get started with reStructuredText. There are also some `Sphinx specific
189 .. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
190 .. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
192 Specific guidelines for the kernel documentation
193 ------------------------------------------------
195 Here are some specific guidelines for the kernel documentation:
197 * Please don't go overboard with reStructuredText markup. Keep it
198 simple. For the most part the documentation should be plain text with
199 just enough consistency in formatting that it can be converted to
202 * Please keep the formatting changes minimal when converting existing
203 documentation to reStructuredText.
205 * Also update the content, not just the formatting, when converting
208 * Please stick to this order of heading adornments:
210 1. ``=`` with overline for document title::
216 2. ``=`` for chapters::
221 3. ``-`` for sections::
226 4. ``~`` for subsections::
231 Although RST doesn't mandate a specific order ("Rather than imposing a fixed
232 number and order of section title adornment styles, the order enforced will be
233 the order as encountered."), having the higher levels the same overall makes
234 it easier to follow the documents.
236 * For inserting fixed width text blocks (for code examples, use case
237 examples, etc.), use ``::`` for anything that doesn't really benefit
238 from syntax highlighting, especially short snippets. Use
239 ``.. code-block:: <language>`` for longer code blocks that benefit
240 from highlighting. For a short snippet of code embedded in the text, use \`\`.
246 The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a
251 .. c:function:: int ioctl( int fd, int request )
253 The C domain of the kernel-doc has some additional features. E.g. you can
254 *rename* the reference name of a function with a common name like ``open`` or
259 .. c:function:: int ioctl( int fd, int request )
260 :name: VIDIOC_LOG_STATUS
262 The func-name (e.g. ioctl) remains in the output but the ref-name changed from
263 ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
264 changed to ``VIDIOC_LOG_STATUS``.
266 Please note that there is no need to use ``c:func:`` to generate cross
267 references to function documentation. Due to some Sphinx extension magic,
268 the documentation build system will automatically turn a reference to
269 ``function()`` into a cross reference if an index entry for the given
270 function name exists. If you see ``c:func:`` use in a kernel document,
271 please feel free to remove it.
277 The list-table formats can be useful for tables that are not easily laid
278 out in the usual Sphinx ASCII-art formats. These formats are nearly
279 impossible for readers of the plain-text documents to understand, though,
280 and should be avoided in the absence of a strong justification for their
283 The ``flat-table`` is a double-stage list similar to the ``list-table`` with
284 some additional features:
286 * column-span: with the role ``cspan`` a cell can be extended through
289 * row-span: with the role ``rspan`` a cell can be extended through
292 * auto span rightmost cell of a table row over the missing cells on the right
293 side of that table-row. With Option ``:fill-cells:`` this behavior can
294 changed from *auto span* to *auto fill*, which automatically inserts (empty)
295 cells instead of spanning the last cell.
299 * ``:header-rows:`` [int] count of header rows
300 * ``:stub-columns:`` [int] count of stub columns
301 * ``:widths:`` [[int] [int] ... ] widths of columns
302 * ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells
306 * ``:cspan:`` [int] additional columns (*morecols*)
307 * ``:rspan:`` [int] additional rows (*morerows*)
309 The example below shows how to use this markup. The first level of the staged
310 list is the *table-row*. In the *table-row* there is only one markup allowed,
311 the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
312 and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
317 .. flat-table:: table title
327 - field 1.2 with autospan
331 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
339 .. flat-table:: table title
349 - field 1.2 with autospan
353 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
362 Cross-referencing from one documentation page to another can be done simply by
363 writing the path to the document file, no special syntax required. The path can
364 be either absolute or relative. For absolute paths, start it with
365 "Documentation/". For example, to cross-reference to this page, all the
366 following are valid options, depending on the current document's directory (note
367 that the ``.rst`` extension is required)::
369 See Documentation/doc-guide/sphinx.rst. This always works.
370 Take a look at sphinx.rst, which is at this same directory.
371 Read ../sphinx.rst, which is one directory above.
373 If you want the link to have a different rendered text other than the document's
374 title, you need to use Sphinx's ``doc`` role. For example::
376 See :doc:`my custom link text for document sphinx <sphinx>`.
378 For most use cases, the former is preferred, as it is cleaner and more suited
379 for people reading the source files. If you come across a ``:doc:`` usage that
380 isn't adding any value, please feel free to convert it to just the document
383 For information on cross-referencing to kernel-doc functions or types, see
384 Documentation/doc-guide/kernel-doc.rst.
391 If you want to add an image, you should use the ``kernel-figure`` and
392 ``kernel-image`` directives. E.g. to insert a figure with a scalable
393 image format, use SVG (:ref:`svg_image_example`)::
395 .. kernel-figure:: svg_image.svg
396 :alt: simple SVG image
400 .. _svg_image_example:
402 .. kernel-figure:: svg_image.svg
403 :alt: simple SVG image
407 The kernel figure (and image) directive supports **DOT** formatted files, see
409 * DOT: http://graphviz.org/pdf/dotguide.pdf
410 * Graphviz: http://www.graphviz.org/content/dot-language
412 A simple example (:ref:`hello_dot_file`)::
414 .. kernel-figure:: hello.dot
417 DOT's hello world example
421 .. kernel-figure:: hello.dot
424 DOT's hello world example
426 Embedded *render* markups (or languages) like Graphviz's **DOT** are provided by the
427 ``kernel-render`` directives.::
429 .. kernel-render:: DOT
431 :caption: Embedded **DOT** (Graphviz) code
437 How this will be rendered depends on the installed tools. If Graphviz is
438 installed, you will see a vector image. If not, the raw markup is inserted as
439 *literal-block* (:ref:`hello_dot_render`).
441 .. _hello_dot_render:
443 .. kernel-render:: DOT
445 :caption: Embedded **DOT** (Graphviz) code
451 The *render* directive has all the options known from the *figure* directive,
452 plus option ``caption``. If ``caption`` has a value, a *figure* node is
453 inserted. If not, an *image* node is inserted. A ``caption`` is also needed, if
454 you want to refer to it (:ref:`hello_svg_render`).
458 .. kernel-render:: SVG
459 :caption: Embedded **SVG** markup
462 <?xml version="1.0" encoding="UTF-8"?>
463 <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
467 .. _hello_svg_render:
469 .. kernel-render:: SVG
470 :caption: Embedded **SVG** markup
473 <?xml version="1.0" encoding="UTF-8"?>
474 <svg xmlns="http://www.w3.org/2000/svg"
475 version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
476 <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
477 <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>