Debian Codegraph @

Documentation/doc-guide/sphinx.rst

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