1 .. _sphinxdoc:
2
3 =====================================
4 Using Sphinx for kernel documentation
5 =====================================
6
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``.
11
12 .. _Sphinx: http://www.sphinx-doc.org/
13 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
14
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.
20
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.
24
25 .. _sphinx_install:
26
27 Sphinx Install
28 ==============
29
30 The ReST markups currently used by the Documentation/ files are meant to be
31 built with ``Sphinx`` version 2.4.4 or higher.
32
33 There's a script that checks for the Sphinx requirements. Please see
34 :ref:`sphinx-pre-install` for further details.
35
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.
39
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.
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
51 In summary, if you want to install the latest version of Sphinx, you
52 should do::
53
54 $ virtualenv sphinx_latest
55 $ . sphinx_latest/bin/activate
56 (sphinx_latest) $ pip install -r Documentation/sphinx/requirements.txt
57
58 After running ``. sphinx_latest/bin/activate``, the prompt will change,
59 in order to indicate that you're using the new environment. If you
60 open a new shell, you need to rerun this command to enter again at
61 the virtual environment before building the documentation.
62
63 Image output
64 ------------
65
66 The kernel documentation build system contains an extension that
67 handles images in both GraphViz and SVG formats (see :ref:`sphinx_kfigure`).
68
69 For it to work, you need to install both GraphViz and ImageMagick
70 packages. If those packages are not installed, the build system will
71 still build the documentation, but won't include any images at the
72 output.
73
74 PDF and LaTeX builds
75 --------------------
76
77 Such builds are currently supported only with Sphinx versions 2.4 and higher.
78
79 For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265.
80
81 Depending on the distribution, you may also need to install a series of
82 ``texlive`` packages that provide the minimal set of functionalities
83 required for ``XeLaTeX`` to work.
84
85 Math Expressions in HTML
86 ------------------------
87
88 Some ReST pages contain math expressions. Due to the way Sphinx works,
89 those expressions are written using LaTeX notation.
90 There are two options for Sphinx to render math expressions in html output.
91 One is an extension called `imgmath`_ which converts math expressions into
92 images and embeds them in html pages.
93 The other is an extension called `mathjax`_ which delegates math rendering
94 to JavaScript capable web browsers.
95 The former was the only option for pre-6.1 kernel documentation and it
96 requires quite a few texlive packages including amsfonts and amsmath among
97 others.
98
99 Since kernel release 6.1, html pages with math expressions can be built
100 without installing any texlive packages. See `Choice of Math Renderer`_ for
101 further 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
108 Checking for Sphinx dependencies
109 --------------------------------
110
111 There's a script that automatically checks for Sphinx dependencies. If it can
112 recognize your distribution, it will also give a hint about the install
113 command 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
127 By default, it checks all the requirements for both html and PDF, including
128 the requirements for images, math expressions and LaTeX build, and assumes
129 that a virtual Python environment will be used. The ones needed for html
130 builds are assumed to be mandatory; the others to be optional.
131
132 It 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
141 Sphinx Build
142 ============
143
144 The usual way to generate the documentation is to run ``make htmldocs`` or
145 ``make pdfdocs``. There are also other formats available: see the documentation
146 section of ``make help``. The generated documentation is placed in
147 format-specific subdirectories under ``Documentation/output``.
148
149 To generate documentation, Sphinx (``sphinx-build``) must obviously be
150 installed. For PDF output you'll also need ``XeLaTeX`` and ``convert(1)``
151 from ImageMagick (https://www.imagemagick.org).\ [#ink]_ All of these are
152 widely available and packaged in distributions.
153
154 To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
155 variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
156 output.
157
158 It is also possible to pass an extra DOCS_CSS overlay file, in order to customize
159 the html layout, by using the ``DOCS_CSS`` make variable.
160
161 By default, the "Alabaster" theme is used to build the HTML documentation;
162 this theme is bundled with Sphinx and need not be installed separately.
163 The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
164
165 There is another make variable ``SPHINXDIRS``, which is useful when test
166 building a subset of documentation. For example, you can build documents
167 under ``Documentation/doc-guide`` by running
168 ``make SPHINXDIRS=doc-guide htmldocs``.
169 The documentation section of ``make help`` will show you the list of
170 subdirectories you can specify.
171
172 To 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
178 Choice of Math Renderer
179 -----------------------
180
181 Since kernel release 6.1, mathjax works as a fallback math renderer for
182 html output.\ [#sph1_8]_
183
184 Math 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
195 The 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
210 Writing Documentation
211 =====================
212
213 Adding new documentation can be as simple as:
214
215 1. Add a new ``.rst`` file somewhere under ``Documentation``.
216 2. 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
220 This is usually good enough for simple documentation (like the one you're
221 reading right now), but for larger documents it may be advisable to create a
222 subdirectory (or use an existing one). For example, the graphics subsystem
223 documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
224 and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
225 the main index.
226
227 See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
228 with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
229 to get started with reStructuredText. There are also some `Sphinx specific
230 markup 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
235 Specific guidelines for the kernel documentation
236 ------------------------------------------------
237
238 Here 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
286 The C domain
287 ------------
288
289 The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a
290 function prototype:
291
292 .. code-block:: rst
293
294 .. c:function:: int ioctl( int fd, int request )
295
296 The 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
305 The 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
307 changed to ``VIDIOC_LOG_STATUS``.
308
309 Please note that there is no need to use ``c:func:`` to generate cross
310 references to function documentation. Due to some Sphinx extension magic,
311 the documentation build system will automatically turn a reference to
312 ``function()`` into a cross reference if an index entry for the given
313 function name exists. If you see ``c:func:`` use in a kernel document,
314 please feel free to remove it.
315
316 Tables
317 ------
318
319 ReStructuredText provides several options for table syntax. Kernel style for
320 tables 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
326 list tables
327 ~~~~~~~~~~~
328
329 The list-table formats can be useful for tables that are not easily laid
330 out in the usual Sphinx ASCII-art formats. These formats are nearly
331 impossible for readers of the plain-text documents to understand, though,
332 and should be avoided in the absence of a strong justification for their
333 use.
334
335 The ``flat-table`` is a double-stage list similar to the ``list-table`` with
336 some 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
349 options:
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
356 roles:
357
358 * ``:cspan:`` [int] additional columns (*morecols*)
359 * ``:rspan:`` [int] additional rows (*morerows*)
360
361 The example below shows how to use this markup. The first level of the staged
362 list is the *table-row*. In the *table-row* there is only one markup allowed,
363 the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
364 and *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
389 Rendered 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
411 Cross-referencing
412 -----------------
413
414 Cross-referencing from one documentation page to another can be done simply by
415 writing the path to the document file, no special syntax required. The path can
416 be either absolute or relative. For absolute paths, start it with
417 "Documentation/". For example, to cross-reference to this page, all the
418 following are valid options, depending on the current document's directory (note
419 that 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
425 If you want the link to have a different rendered text other than the document's
426 title, you need to use Sphinx's ``doc`` role. For example::
427
428 See :doc:`my custom link text for document sphinx <sphinx>`.
429
430 For most use cases, the former is preferred, as it is cleaner and more suited
431 for people reading the source files. If you come across a ``:doc:`` usage that
432 isn't adding any value, please feel free to convert it to just the document
433 path.
434
435 For information on cross-referencing to kernel-doc functions or types, see
436 Documentation/doc-guide/kernel-doc.rst.
437
438 Referencing commits
439 ~~~~~~~~~~~~~~~~~~~
440
441 References to git commits are automatically hyperlinked given that they are
442 written in one of these formats::
443
444 commit 72bf4f1767f0
445 commit 72bf4f1767f0 ("net: do not leave an empty skb in write queue")
446
447 .. _sphinx_kfigure:
448
449 Figures & Images
450 ================
451
452 If you want to add an image, you should use the ``kernel-figure`` and
453 ``kernel-image`` directives. E.g. to insert a figure with a scalable
454 image format, use SVG (:ref:`svg_image_example`)::
455
456 .. kernel-figure:: svg_image.svg
457 :alt: simple SVG image
458
459 SVG image example
460
461 .. _svg_image_example:
462
463 .. kernel-figure:: svg_image.svg
464 :alt: simple SVG image
465
466 SVG image example
467
468 The kernel figure (and image) directive supports **DOT** formatted files, see
469
470 * DOT: http://graphviz.org/pdf/dotguide.pdf
471 * Graphviz: http://www.graphviz.org/content/dot-language
472
473 A simple example (:ref:`hello_dot_file`)::
474
475 .. kernel-figure:: hello.dot
476 :alt: hello world
477
478 DOT's hello world example
479
480 .. _hello_dot_file:
481
482 .. kernel-figure:: hello.dot
483 :alt: hello world
484
485 DOT's hello world example
486
487 Embedded *render* markups (or languages) like Graphviz's **DOT** are provided by the
488 ``kernel-render`` directives.::
489
490 .. kernel-render:: DOT
491 :alt: foobar digraph
492 :caption: Embedded **DOT** (Graphviz) code
493
494 digraph foo {
495 "bar" -> "baz";
496 }
497
498 How this will be rendered depends on the installed tools. If Graphviz is
499 installed, you will see a vector image. If not, the raw markup is inserted as
500 *literal-block* (:ref:`hello_dot_render`).
501
502 .. _hello_dot_render:
503
504 .. kernel-render:: DOT
505 :alt: foobar digraph
506 :caption: Embedded **DOT** (Graphviz) code
507
508 digraph foo {
509 "bar" -> "baz";
510 }
511
512 The *render* directive has all the options known from the *figure* directive,
513 plus option ``caption``. If ``caption`` has a value, a *figure* node is
514 inserted. If not, an *image* node is inserted. A ``caption`` is also needed, if
515 you want to refer to it (:ref:`hello_svg_render`).
516
517 Embedded **SVG**::
518
519 .. kernel-render:: SVG
520 :caption: Embedded **SVG** markup
521 :alt: so-nw-arrow
522
523 <?xml version="1.0" encoding="UTF-8"?>
524 <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
525 ...
526 </svg>
527
528 .. _hello_svg_render:
529
530 .. kernel-render:: SVG
531 :caption: Embedded **SVG** markup
532 :alt: so-nw-arrow
533
534 <?xml version="1.0" encoding="UTF-8"?>
535 <svg xmlns="http://www.w3.org/2000/svg"
536 version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
537 <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
538 <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
539 </svg>
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.