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.7 or higher.
32 There's a script that checks for the Sphinx requirements. Please see
33 :ref:`sphinx-pre-install` for further details.
35 Most distributions are shipped with Sphinx, but its toolchain is fragile,
36 and it is not uncommon that upgrading it or some other Python packages
37 on your machine would cause the documentation build to break.
39 A way to avoid that is to use a different version than the one shipped
40 with your distributions. In order to do so, it is recommended to install
41 Sphinx inside a virtual environment, using ``virtualenv-3``
42 or ``virtualenv``, depending on how your distribution packaged Python 3.
46 #) It is recommended to use the RTD theme for html output. Depending
47 on the Sphinx version, it should be installed separately,
48 with ``pip install sphinx_rtd_theme``.
50 #) Some ReST pages contain math expressions. Due to the way Sphinx works,
51 those expressions are written using LaTeX notation. It needs texlive
52 installed with amsfonts and amsmath in order to evaluate them.
54 In summary, if you want to install Sphinx version 2.4.4, you should do::
56 $ virtualenv sphinx_2.4.4
57 $ . sphinx_2.4.4/bin/activate
58 (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
60 After running ``. sphinx_2.4.4/bin/activate``, the prompt will change,
61 in order to indicate that you're using the new environment. If you
62 open a new shell, you need to rerun this command to enter again at
63 the virtual environment before building the documentation.
68 The kernel documentation build system contains an extension that
69 handles images on both GraphViz and SVG formats (see
70 :ref:`sphinx_kfigure`).
72 For it to work, you need to install both GraphViz and ImageMagick
73 packages. If those packages are not installed, the build system will
74 still build the documentation, but won't include any images at the
80 Such builds are currently supported only with Sphinx versions 2.4 and higher.
82 For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265.
84 Depending on the distribution, you may also need to install a series of
85 ``texlive`` packages that provide the minimal set of functionalities
86 required for ``XeLaTeX`` to work.
88 .. _sphinx-pre-install:
90 Checking for Sphinx dependencies
91 --------------------------------
93 There's a script that automatically check for Sphinx dependencies. If it can
94 recognize your distribution, it will also give a hint about the install
95 command line options for your distro::
97 $ ./scripts/sphinx-pre-install
98 Checking if the needed tools for Fedora release 26 (Twenty Six) are available
99 Warning: better to also install "texlive-luatex85".
102 sudo dnf install -y texlive-luatex85
103 /usr/bin/virtualenv sphinx_2.4.4
104 . sphinx_2.4.4/bin/activate
105 pip install -r Documentation/sphinx/requirements.txt
107 Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
109 By default, it checks all the requirements for both html and PDF, including
110 the requirements for images, math expressions and LaTeX build, and assumes
111 that a virtual Python environment will be used. The ones needed for html
112 builds are assumed to be mandatory; the others to be optional.
114 It supports two optional parameters:
117 Disable checks for PDF;
120 Use OS packaging for Sphinx instead of Python virtual environment.
126 The usual way to generate the documentation is to run ``make htmldocs`` or
127 ``make pdfdocs``. There are also other formats available: see the documentation
128 section of ``make help``. The generated documentation is placed in
129 format-specific subdirectories under ``Documentation/output``.
131 To generate documentation, Sphinx (``sphinx-build``) must obviously be
132 installed. For prettier HTML output, the Read the Docs Sphinx theme
133 (``sphinx_rtd_theme``) is used if available. For PDF output you'll also need
134 ``XeLaTeX`` and ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
135 All of these are widely available and packaged in distributions.
137 To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
138 variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
141 It is also possible to pass an extra DOCS_CSS overlay file, in order to customize
142 the html layout, by using the ``DOCS_CSS`` make variable.
144 By default, the build will try to use the Read the Docs sphinx theme:
146 https://github.com/readthedocs/sphinx_rtd_theme
148 If the theme is not available, it will fall-back to the classic one.
150 The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
152 To remove the generated documentation, run ``make cleandocs``.
154 Writing Documentation
155 =====================
157 Adding new documentation can be as simple as:
159 1. Add a new ``.rst`` file somewhere under ``Documentation``.
160 2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
162 .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
164 This is usually good enough for simple documentation (like the one you're
165 reading right now), but for larger documents it may be advisable to create a
166 subdirectory (or use an existing one). For example, the graphics subsystem
167 documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
168 and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
171 See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
172 with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
173 to get started with reStructuredText. There are also some `Sphinx specific
176 .. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
177 .. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
179 Specific guidelines for the kernel documentation
180 ------------------------------------------------
182 Here are some specific guidelines for the kernel documentation:
184 * Please don't go overboard with reStructuredText markup. Keep it
185 simple. For the most part the documentation should be plain text with
186 just enough consistency in formatting that it can be converted to
189 * Please keep the formatting changes minimal when converting existing
190 documentation to reStructuredText.
192 * Also update the content, not just the formatting, when converting
195 * Please stick to this order of heading adornments:
197 1. ``=`` with overline for document title::
203 2. ``=`` for chapters::
208 3. ``-`` for sections::
213 4. ``~`` for subsections::
218 Although RST doesn't mandate a specific order ("Rather than imposing a fixed
219 number and order of section title adornment styles, the order enforced will be
220 the order as encountered."), having the higher levels the same overall makes
221 it easier to follow the documents.
223 * For inserting fixed width text blocks (for code examples, use case
224 examples, etc.), use ``::`` for anything that doesn't really benefit
225 from syntax highlighting, especially short snippets. Use
226 ``.. code-block:: <language>`` for longer code blocks that benefit
227 from highlighting. For a short snippet of code embedded in the text, use \`\`.
233 The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a
238 .. c:function:: int ioctl( int fd, int request )
240 The C domain of the kernel-doc has some additional features. E.g. you can
241 *rename* the reference name of a function with a common name like ``open`` or
246 .. c:function:: int ioctl( int fd, int request )
247 :name: VIDIOC_LOG_STATUS
249 The func-name (e.g. ioctl) remains in the output but the ref-name changed from
250 ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
251 changed to ``VIDIOC_LOG_STATUS``.
253 Please note that there is no need to use ``c:func:`` to generate cross
254 references to function documentation. Due to some Sphinx extension magic,
255 the documentation build system will automatically turn a reference to
256 ``function()`` into a cross reference if an index entry for the given
257 function name exists. If you see ``c:func:`` use in a kernel document,
258 please feel free to remove it.
264 The list-table formats can be useful for tables that are not easily laid
265 out in the usual Sphinx ASCII-art formats. These formats are nearly
266 impossible for readers of the plain-text documents to understand, though,
267 and should be avoided in the absence of a strong justification for their
270 The ``flat-table`` is a double-stage list similar to the ``list-table`` with
271 some additional features:
273 * column-span: with the role ``cspan`` a cell can be extended through
276 * row-span: with the role ``rspan`` a cell can be extended through
279 * auto span rightmost cell of a table row over the missing cells on the right
280 side of that table-row. With Option ``:fill-cells:`` this behavior can
281 changed from *auto span* to *auto fill*, which automatically inserts (empty)
282 cells instead of spanning the last cell.
286 * ``:header-rows:`` [int] count of header rows
287 * ``:stub-columns:`` [int] count of stub columns
288 * ``:widths:`` [[int] [int] ... ] widths of columns
289 * ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells
293 * ``:cspan:`` [int] additional columns (*morecols*)
294 * ``:rspan:`` [int] additional rows (*morerows*)
296 The example below shows how to use this markup. The first level of the staged
297 list is the *table-row*. In the *table-row* there is only one markup allowed,
298 the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
299 and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
304 .. flat-table:: table title
314 - field 1.2 with autospan
318 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
326 .. flat-table:: table title
336 - field 1.2 with autospan
340 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
349 Cross-referencing from one documentation page to another can be done simply by
350 writing the path to the document file, no special syntax required. The path can
351 be either absolute or relative. For absolute paths, start it with
352 "Documentation/". For example, to cross-reference to this page, all the
353 following are valid options, depending on the current document's directory (note
354 that the ``.rst`` extension is required)::
356 See Documentation/doc-guide/sphinx.rst. This always works.
357 Take a look at sphinx.rst, which is at this same directory.
358 Read ../sphinx.rst, which is one directory above.
360 If you want the link to have a different rendered text other than the document's
361 title, you need to use Sphinx's ``doc`` role. For example::
363 See :doc:`my custom link text for document sphinx <sphinx>`.
365 For most use cases, the former is preferred, as it is cleaner and more suited
366 for people reading the source files. If you come across a ``:doc:`` usage that
367 isn't adding any value, please feel free to convert it to just the document
370 For information on cross-referencing to kernel-doc functions or types, see
371 Documentation/doc-guide/kernel-doc.rst.
378 If you want to add an image, you should use the ``kernel-figure`` and
379 ``kernel-image`` directives. E.g. to insert a figure with a scalable
380 image format, use SVG (:ref:`svg_image_example`)::
382 .. kernel-figure:: svg_image.svg
383 :alt: simple SVG image
387 .. _svg_image_example:
389 .. kernel-figure:: svg_image.svg
390 :alt: simple SVG image
394 The kernel figure (and image) directive supports **DOT** formatted files, see
396 * DOT: http://graphviz.org/pdf/dotguide.pdf
397 * Graphviz: http://www.graphviz.org/content/dot-language
399 A simple example (:ref:`hello_dot_file`)::
401 .. kernel-figure:: hello.dot
404 DOT's hello world example
408 .. kernel-figure:: hello.dot
411 DOT's hello world example
413 Embedded *render* markups (or languages) like Graphviz's **DOT** are provided by the
414 ``kernel-render`` directives.::
416 .. kernel-render:: DOT
418 :caption: Embedded **DOT** (Graphviz) code
424 How this will be rendered depends on the installed tools. If Graphviz is
425 installed, you will see a vector image. If not, the raw markup is inserted as
426 *literal-block* (:ref:`hello_dot_render`).
428 .. _hello_dot_render:
430 .. kernel-render:: DOT
432 :caption: Embedded **DOT** (Graphviz) code
438 The *render* directive has all the options known from the *figure* directive,
439 plus option ``caption``. If ``caption`` has a value, a *figure* node is
440 inserted. If not, an *image* node is inserted. A ``caption`` is also needed, if
441 you want to refer to it (:ref:`hello_svg_render`).
445 .. kernel-render:: SVG
446 :caption: Embedded **SVG** markup
449 <?xml version="1.0" encoding="UTF-8"?>
450 <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
454 .. _hello_svg_render:
456 .. kernel-render:: SVG
457 :caption: Embedded **SVG** markup
460 <?xml version="1.0" encoding="UTF-8"?>
461 <svg xmlns="http://www.w3.org/2000/svg"
462 version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
463 <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
464 <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>