1.. _sphinxdoc:
2
3=====================================
4Using Sphinx for kernel documentation
5=====================================
6
7The Linux kernel uses `Sphinx`_ to generate pretty documentation from
8`reStructuredText`_ files under ``Documentation``. To build the documentation in
9HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated
10documentation is placed in ``Documentation/output``.
11
12.. _Sphinx: http://www.sphinx-doc.org/
13.. _reStructuredText: http://docutils.sourceforge.net/rst.html
14
15The reStructuredText files may contain directives to include structured
16documentation comments, or kernel-doc comments, from source files. Usually these
17are used to describe the functions and types and design of the code. The
18kernel-doc comments have some special structure and formatting, but beyond that
19they are also treated as reStructuredText.
20
21Finally, there are thousands of plain text documentation files scattered around
22``Documentation``. Some of these will likely be converted to reStructuredText
23over time, but the bulk of them will remain in plain text.
24
25.. _sphinx_install:
26
27Sphinx Install
28==============
29
30The ReST markups currently used by the Documentation/ files are meant to be
31built with ``Sphinx`` version 1.7 or higher.
32
33There's a script that checks for the Sphinx requirements. Please see
34:ref:`sphinx-pre-install` for further details.
35
36Most distributions are shipped with Sphinx, but its toolchain is fragile,
37and it is not uncommon that upgrading it or some other Python packages
38on your machine would cause the documentation build to break.
39
40A way to avoid that is to use a different version than the one shipped
41with your distributions. In order to do so, it is recommended to install
42Sphinx inside a virtual environment, using ``virtualenv-3``
43or ``virtualenv``, depending on how your distribution packaged Python 3.
44
45.. note::
46
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``.
50
51In summary, if you want to install Sphinx version 2.4.4, you should do::
52
53       $ virtualenv sphinx_2.4.4
54       $ . sphinx_2.4.4/bin/activate
55       (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
56
57After running ``. sphinx_2.4.4/bin/activate``, the prompt will change,
58in order to indicate that you're using the new environment. If you
59open a new shell, you need to rerun this command to enter again at
60the virtual environment before building the documentation.
61
62Image output
63------------
64
65The kernel documentation build system contains an extension that
66handles images on both GraphViz and SVG formats (see
67:ref:`sphinx_kfigure`).
68
69For it to work, you need to install both GraphViz and ImageMagick
70packages. If those packages are not installed, the build system will
71still build the documentation, but won't include any images at the
72output.
73
74PDF and LaTeX builds
75--------------------
76
77Such builds are currently supported only with Sphinx versions 2.4 and higher.
78
79For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265.
80
81Depending on the distribution, you may also need to install a series of
82``texlive`` packages that provide the minimal set of functionalities
83required for ``XeLaTeX`` to work.
84
85Math Expressions in HTML
86------------------------
87
88Some ReST pages contain math expressions. Due to the way Sphinx works,
89those expressions are written using LaTeX notation.
90There are two options for Sphinx to render math expressions in html output.
91One is an extension called `imgmath`_ which converts math expressions into
92images and embeds them in html pages.
93The other is an extension called `mathjax`_ which delegates math rendering
94to JavaScript capable web browsers.
95The former was the only option for pre-6.1 kernel documentation and it
96requires quite a few texlive packages including amsfonts and amsmath among
97others.
98
99Since kernel release 6.1, html pages with math expressions can be built
100without installing any texlive packages. See `Choice of Math Renderer`_ for
101further info.
102
103.. _imgmath: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.imgmath
104.. _mathjax: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax
105
106.. _sphinx-pre-install:
107
108Checking for Sphinx dependencies
109--------------------------------
110
111There's a script that automatically check for Sphinx dependencies. If it can
112recognize your distribution, it will also give a hint about the install
113command line options for your distro::
114
115	$ ./scripts/sphinx-pre-install
116	Checking if the needed tools for Fedora release 26 (Twenty Six) are available
117	Warning: better to also install "texlive-luatex85".
118	You should run:
119
120		sudo dnf install -y texlive-luatex85
121		/usr/bin/virtualenv sphinx_2.4.4
122		. sphinx_2.4.4/bin/activate
123		pip install -r Documentation/sphinx/requirements.txt
124
125	Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
126
127By default, it checks all the requirements for both html and PDF, including
128the requirements for images, math expressions and LaTeX build, and assumes
129that a virtual Python environment will be used. The ones needed for html
130builds are assumed to be mandatory; the others to be optional.
131
132It supports two optional parameters:
133
134``--no-pdf``
135	Disable checks for PDF;
136
137``--no-virtualenv``
138	Use OS packaging for Sphinx instead of Python virtual environment.
139
140
141Sphinx Build
142============
143
144The usual way to generate the documentation is to run ``make htmldocs`` or
145``make pdfdocs``. There are also other formats available: see the documentation
146section of ``make help``. The generated documentation is placed in
147format-specific subdirectories under ``Documentation/output``.
148
149To generate documentation, Sphinx (``sphinx-build``) must obviously be
150installed.  For PDF output you'll also need ``XeLaTeX`` and ``convert(1)``
151from ImageMagick (https://www.imagemagick.org).\ [#ink]_ All of these are
152widely available and packaged in distributions.
153
154To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
155variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
156output.
157
158It is also possible to pass an extra DOCS_CSS overlay file, in order to customize
159the html layout, by using the ``DOCS_CSS`` make variable.
160
161By default, the "Alabaster" theme is used to build the HTML documentation;
162this theme is bundled with Sphinx and need not be installed separately.
163The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
164
165There is another make variable ``SPHINXDIRS``, which is useful when test
166building a subset of documentation.  For example, you can build documents
167under ``Documentation/doc-guide`` by running
168``make SPHINXDIRS=doc-guide htmldocs``.
169The documentation section of ``make help`` will show you the list of
170subdirectories you can specify.
171
172To remove the generated documentation, run ``make cleandocs``.
173
174.. [#ink] Having ``inkscape(1)`` from Inkscape (https://inkscape.org)
175	  as well would improve the quality of images embedded in PDF
176	  documents, especially for kernel releases 5.18 and later.
177
178Choice of Math Renderer
179-----------------------
180
181Since kernel release 6.1, mathjax works as a fallback math renderer for
182html output.\ [#sph1_8]_
183
184Math renderer is chosen depending on available commands as shown below:
185
186.. table:: Math Renderer Choices for HTML
187
188    ============= ================= ============
189    Math renderer Required commands Image format
190    ============= ================= ============
191    imgmath       latex, dvipng     PNG (raster)
192    mathjax
193    ============= ================= ============
194
195The choice can be overridden by setting an environment variable
196``SPHINX_IMGMATH`` as shown below:
197
198.. table:: Effect of Setting ``SPHINX_IMGMATH``
199
200    ====================== ========
201    Setting                Renderer
202    ====================== ========
203    ``SPHINX_IMGMATH=yes`` imgmath
204    ``SPHINX_IMGMATH=no``  mathjax
205    ====================== ========
206
207.. [#sph1_8] Fallback of math renderer requires Sphinx >=1.8.
208
209
210Writing Documentation
211=====================
212
213Adding new documentation can be as simple as:
214
2151. Add a new ``.rst`` file somewhere under ``Documentation``.
2162. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
217
218.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
219
220This is usually good enough for simple documentation (like the one you're
221reading right now), but for larger documents it may be advisable to create a
222subdirectory (or use an existing one). For example, the graphics subsystem
223documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
224and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
225the main index.
226
227See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
228with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
229to get started with reStructuredText. There are also some `Sphinx specific
230markup constructs`_.
231
232.. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
233.. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
234
235Specific guidelines for the kernel documentation
236------------------------------------------------
237
238Here are some specific guidelines for the kernel documentation:
239
240* Please don't go overboard with reStructuredText markup. Keep it
241  simple. For the most part the documentation should be plain text with
242  just enough consistency in formatting that it can be converted to
243  other formats.
244
245* Please keep the formatting changes minimal when converting existing
246  documentation to reStructuredText.
247
248* Also update the content, not just the formatting, when converting
249  documentation.
250
251* Please stick to this order of heading adornments:
252
253  1. ``=`` with overline for document title::
254
255       ==============
256       Document title
257       ==============
258
259  2. ``=`` for chapters::
260
261       Chapters
262       ========
263
264  3. ``-`` for sections::
265
266       Section
267       -------
268
269  4. ``~`` for subsections::
270
271       Subsection
272       ~~~~~~~~~~
273
274  Although RST doesn't mandate a specific order ("Rather than imposing a fixed
275  number and order of section title adornment styles, the order enforced will be
276  the order as encountered."), having the higher levels the same overall makes
277  it easier to follow the documents.
278
279* For inserting fixed width text blocks (for code examples, use case
280  examples, etc.), use ``::`` for anything that doesn't really benefit
281  from syntax highlighting, especially short snippets. Use
282  ``.. code-block:: <language>`` for longer code blocks that benefit
283  from highlighting. For a short snippet of code embedded in the text, use \`\`.
284
285
286the C domain
287------------
288
289The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a
290function prototype:
291
292.. code-block:: rst
293
294    .. c:function:: int ioctl( int fd, int request )
295
296The C domain of the kernel-doc has some additional features. E.g. you can
297*rename* the reference name of a function with a common name like ``open`` or
298``ioctl``:
299
300.. code-block:: rst
301
302     .. c:function:: int ioctl( int fd, int request )
303        :name: VIDIOC_LOG_STATUS
304
305The func-name (e.g. ioctl) remains in the output but the ref-name changed from
306``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
307changed to ``VIDIOC_LOG_STATUS``.
308
309Please note that there is no need to use ``c:func:`` to generate cross
310references to function documentation.  Due to some Sphinx extension magic,
311the documentation build system will automatically turn a reference to
312``function()`` into a cross reference if an index entry for the given
313function name exists.  If you see ``c:func:`` use in a kernel document,
314please feel free to remove it.
315
316Tables
317------
318
319ReStructuredText provides several options for table syntax. Kernel style for
320tables is to prefer *simple table* syntax or *grid table* syntax. See the
321`reStructuredText user reference for table syntax`_ for more details.
322
323.. _reStructuredText user reference for table syntax:
324   https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables
325
326list tables
327~~~~~~~~~~~
328
329The list-table formats can be useful for tables that are not easily laid
330out in the usual Sphinx ASCII-art formats.  These formats are nearly
331impossible for readers of the plain-text documents to understand, though,
332and should be avoided in the absence of a strong justification for their
333use.
334
335The ``flat-table`` is a double-stage list similar to the ``list-table`` with
336some additional features:
337
338* column-span: with the role ``cspan`` a cell can be extended through
339  additional columns
340
341* row-span: with the role ``rspan`` a cell can be extended through
342  additional rows
343
344* auto span rightmost cell of a table row over the missing cells on the right
345  side of that table-row.  With Option ``:fill-cells:`` this behavior can
346  changed from *auto span* to *auto fill*, which automatically inserts (empty)
347  cells instead of spanning the last cell.
348
349options:
350
351* ``:header-rows:``   [int] count of header rows
352* ``:stub-columns:``  [int] count of stub columns
353* ``:widths:``        [[int] [int] ... ] widths of columns
354* ``:fill-cells:``    instead of auto-spanning missing cells, insert missing cells
355
356roles:
357
358* ``:cspan:`` [int] additional columns (*morecols*)
359* ``:rspan:`` [int] additional rows (*morerows*)
360
361The example below shows how to use this markup.  The first level of the staged
362list is the *table-row*. In the *table-row* there is only one markup allowed,
363the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
364and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
365<last row>`).
366
367.. code-block:: rst
368
369   .. flat-table:: table title
370      :widths: 2 1 1 3
371
372      * - head col 1
373        - head col 2
374        - head col 3
375        - head col 4
376
377      * - row 1
378        - field 1.1
379        - field 1.2 with autospan
380
381      * - row 2
382        - field 2.1
383        - :rspan:`1` :cspan:`1` field 2.2 - 3.3
384
385      * .. _`last row`:
386
387        - row 3
388
389Rendered as:
390
391   .. flat-table:: table title
392      :widths: 2 1 1 3
393
394      * - head col 1
395        - head col 2
396        - head col 3
397        - head col 4
398
399      * - row 1
400        - field 1.1
401        - field 1.2 with autospan
402
403      * - row 2
404        - field 2.1
405        - :rspan:`1` :cspan:`1` field 2.2 - 3.3
406
407      * .. _`last row`:
408
409        - row 3
410
411Cross-referencing
412-----------------
413
414Cross-referencing from one documentation page to another can be done simply by
415writing the path to the document file, no special syntax required. The path can
416be either absolute or relative. For absolute paths, start it with
417"Documentation/". For example, to cross-reference to this page, all the
418following are valid options, depending on the current document's directory (note
419that the ``.rst`` extension is required)::
420
421    See Documentation/doc-guide/sphinx.rst. This always works.
422    Take a look at sphinx.rst, which is at this same directory.
423    Read ../sphinx.rst, which is one directory above.
424
425If you want the link to have a different rendered text other than the document's
426title, you need to use Sphinx's ``doc`` role. For example::
427
428    See :doc:`my custom link text for document sphinx <sphinx>`.
429
430For most use cases, the former is preferred, as it is cleaner and more suited
431for people reading the source files. If you come across a ``:doc:`` usage that
432isn't adding any value, please feel free to convert it to just the document
433path.
434
435For information on cross-referencing to kernel-doc functions or types, see
436Documentation/doc-guide/kernel-doc.rst.
437
438.. _sphinx_kfigure:
439
440Figures & Images
441================
442
443If you want to add an image, you should use the ``kernel-figure`` and
444``kernel-image`` directives. E.g. to insert a figure with a scalable
445image format, use SVG (:ref:`svg_image_example`)::
446
447    .. kernel-figure::  svg_image.svg
448       :alt:    simple SVG image
449
450       SVG image example
451
452.. _svg_image_example:
453
454.. kernel-figure::  svg_image.svg
455   :alt:    simple SVG image
456
457   SVG image example
458
459The kernel figure (and image) directive supports **DOT** formatted files, see
460
461* DOT: http://graphviz.org/pdf/dotguide.pdf
462* Graphviz: http://www.graphviz.org/content/dot-language
463
464A simple example (:ref:`hello_dot_file`)::
465
466  .. kernel-figure::  hello.dot
467     :alt:    hello world
468
469     DOT's hello world example
470
471.. _hello_dot_file:
472
473.. kernel-figure::  hello.dot
474   :alt:    hello world
475
476   DOT's hello world example
477
478Embedded *render* markups (or languages) like Graphviz's **DOT** are provided by the
479``kernel-render`` directives.::
480
481  .. kernel-render:: DOT
482     :alt: foobar digraph
483     :caption: Embedded **DOT** (Graphviz) code
484
485     digraph foo {
486      "bar" -> "baz";
487     }
488
489How this will be rendered depends on the installed tools. If Graphviz is
490installed, you will see a vector image. If not, the raw markup is inserted as
491*literal-block* (:ref:`hello_dot_render`).
492
493.. _hello_dot_render:
494
495.. kernel-render:: DOT
496   :alt: foobar digraph
497   :caption: Embedded **DOT** (Graphviz) code
498
499   digraph foo {
500      "bar" -> "baz";
501   }
502
503The *render* directive has all the options known from the *figure* directive,
504plus option ``caption``.  If ``caption`` has a value, a *figure* node is
505inserted. If not, an *image* node is inserted. A ``caption`` is also needed, if
506you want to refer to it (:ref:`hello_svg_render`).
507
508Embedded **SVG**::
509
510  .. kernel-render:: SVG
511     :caption: Embedded **SVG** markup
512     :alt: so-nw-arrow
513
514     <?xml version="1.0" encoding="UTF-8"?>
515     <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
516        ...
517     </svg>
518
519.. _hello_svg_render:
520
521.. kernel-render:: SVG
522   :caption: Embedded **SVG** markup
523   :alt: so-nw-arrow
524
525   <?xml version="1.0" encoding="UTF-8"?>
526   <svg xmlns="http://www.w3.org/2000/svg"
527     version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
528   <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
529   <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
530   </svg>
531