Linux 6.12-rc1
[linux-2.6-block.git] / Documentation / doc-guide / sphinx.rst
CommitLineData
f77af637
FV
1.. _sphinxdoc:
2
452c4915
BS
3=====================================
4Using Sphinx for kernel documentation
5=====================================
1dc4bbf0
MCC
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
1dc4bbf0
MCC
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
b8b07b5c
MCC
25.. _sphinx_install:
26
27Sphinx Install
28==============
29
30The ReST markups currently used by the Documentation/ files are meant to be
3e893e16 31built with ``Sphinx`` version 2.4.4 or higher.
b8b07b5c 32
c1ec85ff 33There's a script that checks for the Sphinx requirements. Please see
868366aa
MCC
34:ref:`sphinx-pre-install` for further details.
35
58ef4a42
MCC
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
4d01460e
JN
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
58ef4a42
MCC
42Sphinx inside a virtual environment, using ``virtualenv-3``
43or ``virtualenv``, depending on how your distribution packaged Python 3.
44
45.. note::
46
58ef4a42 47 #) It is recommended to use the RTD theme for html output. Depending
0be1511f 48 on the Sphinx version, it should be installed separately,
58ef4a42
MCC
49 with ``pip install sphinx_rtd_theme``.
50
b31274d5
LB
51In summary, if you want to install the latest version of Sphinx, you
52should do::
58ef4a42 53
b31274d5
LB
54 $ virtualenv sphinx_latest
55 $ . sphinx_latest/bin/activate
56 (sphinx_latest) $ pip install -r Documentation/sphinx/requirements.txt
58ef4a42 57
b31274d5 58After running ``. sphinx_latest/bin/activate``, the prompt will change,
58ef4a42
MCC
59in order to indicate that you're using the new environment. If you
60open a new shell, you need to rerun this command to enter again at
61the virtual environment before building the documentation.
62
d43e5ae9
MCC
63Image output
64------------
65
66The kernel documentation build system contains an extension that
40be2369 67handles images in both GraphViz and SVG formats (see :ref:`sphinx_kfigure`).
d43e5ae9
MCC
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
6e322a17
MCC
74PDF and LaTeX builds
75--------------------
76
6d6a8d6a 77Such builds are currently supported only with Sphinx versions 2.4 and higher.
6e322a17
MCC
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
868366aa
MCC
83required for ``XeLaTeX`` to work.
84
679b4bc2
AY
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
868366aa
MCC
106.. _sphinx-pre-install:
107
108Checking for Sphinx dependencies
109--------------------------------
110
40be2369 111There's a script that automatically checks for Sphinx dependencies. If it can
868366aa
MCC
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
6d6a8d6a
AY
121 /usr/bin/virtualenv sphinx_2.4.4
122 . sphinx_2.4.4/bin/activate
868366aa
MCC
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
6e322a17 140
1dc4bbf0
MCC
141Sphinx Build
142============
143
144The usual way to generate the documentation is to run ``make htmldocs`` or
0be1511f 145``make pdfdocs``. There are also other formats available: see the documentation
1dc4bbf0
MCC
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
26d797ff
JC
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.
1dc4bbf0
MCC
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
135707d3
MCC
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
26d797ff
JC
161By default, the "Alabaster" theme is used to build the HTML documentation;
162this theme is bundled with Sphinx and need not be installed separately.
0e805b11 163The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
fca7216b 164
4d627ef1
AY
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
1dc4bbf0
MCC
172To remove the generated documentation, run ``make cleandocs``.
173
7c43214d
AY
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
679b4bc2
AY
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
1dc4bbf0
MCC
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
c3c53600
DV
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.
1dc4bbf0
MCC
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
c3c53600
DV
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
83e8b971 283 from highlighting. For a short snippet of code embedded in the text, use \`\`.
c3c53600 284
1dc4bbf0 285
40be2369 286The C domain
1dc4bbf0
MCC
287------------
288
29fd35bd 289The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a
1dc4bbf0
MCC
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
d9d7c0c4
JC
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.
1dc4bbf0 315
35d4a3c6
JS
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
1dc4bbf0
MCC
325
326list tables
35d4a3c6 327~~~~~~~~~~~
1dc4bbf0 328
db67eb74
JC
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.
1dc4bbf0
MCC
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
0be1511f 377 * - row 1
1dc4bbf0
MCC
378 - field 1.1
379 - field 1.2 with autospan
380
0be1511f 381 * - row 2
1dc4bbf0
MCC
382 - field 2.1
383 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
384
385 * .. _`last row`:
386
0be1511f 387 - row 3
1dc4bbf0
MCC
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
0be1511f 399 * - row 1
1dc4bbf0
MCC
400 - field 1.1
401 - field 1.2 with autospan
402
0be1511f 403 * - row 2
1dc4bbf0
MCC
404 - field 2.1
405 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
406
407 * .. _`last row`:
408
0be1511f 409 - row 3
db6ccf23 410
c170f2eb
NP
411Cross-referencing
412-----------------
413
1e013ff7
NP
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.
c170f2eb
NP
434
435For information on cross-referencing to kernel-doc functions or types, see
436Documentation/doc-guide/kernel-doc.rst.
437
86b17aaf
VN
438Referencing commits
439~~~~~~~~~~~~~~~~~~~
440
441References to git commits are automatically hyperlinked given that they are
442written in one of these formats::
443
444 commit 72bf4f1767f0
445 commit 72bf4f1767f0 ("net: do not leave an empty skb in write queue")
446
d43e5ae9 447.. _sphinx_kfigure:
db6ccf23
MH
448
449Figures & Images
450================
451
452If 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
0be1511f 454image format, use SVG (:ref:`svg_image_example`)::
db6ccf23
MH
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
0be1511f 468The kernel figure (and image) directive supports **DOT** formatted files, see
db6ccf23
MH
469
470* DOT: http://graphviz.org/pdf/dotguide.pdf
471* Graphviz: http://www.graphviz.org/content/dot-language
472
473A 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
0be1511f 487Embedded *render* markups (or languages) like Graphviz's **DOT** are provided by the
db6ccf23
MH
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
498How this will be rendered depends on the installed tools. If Graphviz is
0be1511f 499installed, you will see a vector image. If not, the raw markup is inserted as
db6ccf23
MH
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
512The *render* directive has all the options known from the *figure* directive,
513plus option ``caption``. If ``caption`` has a value, a *figure* node is
0be1511f
RD
514inserted. If not, an *image* node is inserted. A ``caption`` is also needed, if
515you want to refer to it (:ref:`hello_svg_render`).
db6ccf23
MH
516
517Embedded **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>