Loading...
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 2.4.4 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 the latest version of Sphinx, you
52should do::
53
54 $ virtualenv sphinx_latest
55 $ . sphinx_latest/bin/activate
56 (sphinx_latest) $ pip install -r Documentation/sphinx/requirements.txt
57
58After running ``. sphinx_latest/bin/activate``, the prompt will change,
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
63Image output
64------------
65
66The kernel documentation build system contains an extension that
67handles images in both GraphViz and SVG formats (see :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 checks 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
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
447.. _sphinx_kfigure:
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
454image 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
468The 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
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
487Embedded *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
498How this will be rendered depends on the installed tools. If Graphviz is
499installed, 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
512The *render* directive has all the options known from the *figure* directive,
513plus option ``caption``. If ``caption`` has a value, a *figure* node is
514inserted. If not, an *image* node is inserted. A ``caption`` is also needed, if
515you want to refer to it (:ref:`hello_svg_render`).
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>
1Introduction
2============
3
4The Linux kernel uses `Sphinx`_ to generate pretty documentation from
5`reStructuredText`_ files under ``Documentation``. To build the documentation in
6HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated
7documentation is placed in ``Documentation/output``.
8
9.. _Sphinx: http://www.sphinx-doc.org/
10.. _reStructuredText: http://docutils.sourceforge.net/rst.html
11
12The reStructuredText files may contain directives to include structured
13documentation comments, or kernel-doc comments, from source files. Usually these
14are used to describe the functions and types and design of the code. The
15kernel-doc comments have some special structure and formatting, but beyond that
16they are also treated as reStructuredText.
17
18Finally, there are thousands of plain text documentation files scattered around
19``Documentation``. Some of these will likely be converted to reStructuredText
20over time, but the bulk of them will remain in plain text.
21
22.. _sphinx_install:
23
24Sphinx Install
25==============
26
27The ReST markups currently used by the Documentation/ files are meant to be
28built with ``Sphinx`` version 1.3 or upper. If you're desiring to build
29PDF outputs, it is recommended to use version 1.4.6 or upper.
30
31There's a script that checks for the Spinx requirements. Please see
32:ref:`sphinx-pre-install` for further details.
33
34Most distributions are shipped with Sphinx, but its toolchain is fragile,
35and it is not uncommon that upgrading it or some other Python packages
36on your machine would cause the documentation build to break.
37
38A way to get rid of that is to use a different version than the one shipped
39on your distributions. In order to do that, it is recommended to install
40Sphinx inside a virtual environment, using ``virtualenv-3``
41or ``virtualenv``, depending on how your distribution packaged Python 3.
42
43.. note::
44
45 #) Sphinx versions below 1.5 don't work properly with Python's
46 docutils version 0.13.1 or upper. So, if you're willing to use
47 those versions, you should run ``pip install 'docutils==0.12'``.
48
49 #) It is recommended to use the RTD theme for html output. Depending
50 on the Sphinx version, it should be installed in separate,
51 with ``pip install sphinx_rtd_theme``.
52
53 #) Some ReST pages contain math expressions. Due to the way Sphinx work,
54 those expressions are written using LaTeX notation. It needs texlive
55 installed with amdfonts and amsmath in order to evaluate them.
56
57In summary, if you want to install Sphinx version 1.4.9, you should do::
58
59 $ virtualenv sphinx_1.4
60 $ . sphinx_1.4/bin/activate
61 (sphinx_1.4) $ pip install -r Documentation/sphinx/requirements.txt
62
63After running ``. sphinx_1.4/bin/activate``, the prompt will change,
64in order to indicate that you're using the new environment. If you
65open a new shell, you need to rerun this command to enter again at
66the virtual environment before building the documentation.
67
68Image output
69------------
70
71The kernel documentation build system contains an extension that
72handles images on both GraphViz and SVG formats (see
73:ref:`sphinx_kfigure`).
74
75For it to work, you need to install both GraphViz and ImageMagick
76packages. If those packages are not installed, the build system will
77still build the documentation, but won't include any images at the
78output.
79
80PDF and LaTeX builds
81--------------------
82
83Such builds are currently supported only with Sphinx versions 1.4 and upper.
84
85For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265.
86
87Depending on the distribution, you may also need to install a series of
88``texlive`` packages that provide the minimal set of functionalities
89required for ``XeLaTeX`` to work.
90
91.. _sphinx-pre-install:
92
93Checking for Sphinx dependencies
94--------------------------------
95
96There's a script that automatically check for Sphinx dependencies. If it can
97recognize your distribution, it will also give a hint about the install
98command line options for your distro::
99
100 $ ./scripts/sphinx-pre-install
101 Checking if the needed tools for Fedora release 26 (Twenty Six) are available
102 Warning: better to also install "texlive-luatex85".
103 You should run:
104
105 sudo dnf install -y texlive-luatex85
106 /usr/bin/virtualenv sphinx_1.4
107 . sphinx_1.4/bin/activate
108 pip install -r Documentation/sphinx/requirements.txt
109
110 Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
111
112By default, it checks all the requirements for both html and PDF, including
113the requirements for images, math expressions and LaTeX build, and assumes
114that a virtual Python environment will be used. The ones needed for html
115builds are assumed to be mandatory; the others to be optional.
116
117It supports two optional parameters:
118
119``--no-pdf``
120 Disable checks for PDF;
121
122``--no-virtualenv``
123 Use OS packaging for Sphinx instead of Python virtual environment.
124
125
126Sphinx Build
127============
128
129The usual way to generate the documentation is to run ``make htmldocs`` or
130``make pdfdocs``. There are also other formats available, see the documentation
131section of ``make help``. The generated documentation is placed in
132format-specific subdirectories under ``Documentation/output``.
133
134To generate documentation, Sphinx (``sphinx-build``) must obviously be
135installed. For prettier HTML output, the Read the Docs Sphinx theme
136(``sphinx_rtd_theme``) is used if available. For PDF output you'll also need
137``XeLaTeX`` and ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
138All of these are widely available and packaged in distributions.
139
140To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
141variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
142output.
143
144To remove the generated documentation, run ``make cleandocs``.
145
146Writing Documentation
147=====================
148
149Adding new documentation can be as simple as:
150
1511. Add a new ``.rst`` file somewhere under ``Documentation``.
1522. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
153
154.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
155
156This is usually good enough for simple documentation (like the one you're
157reading right now), but for larger documents it may be advisable to create a
158subdirectory (or use an existing one). For example, the graphics subsystem
159documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
160and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
161the main index.
162
163See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
164with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
165to get started with reStructuredText. There are also some `Sphinx specific
166markup constructs`_.
167
168.. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
169.. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
170
171Specific guidelines for the kernel documentation
172------------------------------------------------
173
174Here are some specific guidelines for the kernel documentation:
175
176* Please don't go overboard with reStructuredText markup. Keep it
177 simple. For the most part the documentation should be plain text with
178 just enough consistency in formatting that it can be converted to
179 other formats.
180
181* Please keep the formatting changes minimal when converting existing
182 documentation to reStructuredText.
183
184* Also update the content, not just the formatting, when converting
185 documentation.
186
187* Please stick to this order of heading adornments:
188
189 1. ``=`` with overline for document title::
190
191 ==============
192 Document title
193 ==============
194
195 2. ``=`` for chapters::
196
197 Chapters
198 ========
199
200 3. ``-`` for sections::
201
202 Section
203 -------
204
205 4. ``~`` for subsections::
206
207 Subsection
208 ~~~~~~~~~~
209
210 Although RST doesn't mandate a specific order ("Rather than imposing a fixed
211 number and order of section title adornment styles, the order enforced will be
212 the order as encountered."), having the higher levels the same overall makes
213 it easier to follow the documents.
214
215* For inserting fixed width text blocks (for code examples, use case
216 examples, etc.), use ``::`` for anything that doesn't really benefit
217 from syntax highlighting, especially short snippets. Use
218 ``.. code-block:: <language>`` for longer code blocks that benefit
219 from highlighting.
220
221
222the C domain
223------------
224
225The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a
226function prototype:
227
228.. code-block:: rst
229
230 .. c:function:: int ioctl( int fd, int request )
231
232The C domain of the kernel-doc has some additional features. E.g. you can
233*rename* the reference name of a function with a common name like ``open`` or
234``ioctl``:
235
236.. code-block:: rst
237
238 .. c:function:: int ioctl( int fd, int request )
239 :name: VIDIOC_LOG_STATUS
240
241The func-name (e.g. ioctl) remains in the output but the ref-name changed from
242``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
243changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by:
244
245.. code-block:: rst
246
247 :c:func:`VIDIOC_LOG_STATUS`
248
249
250list tables
251-----------
252
253We recommend the use of *list table* formats. The *list table* formats are
254double-stage lists. Compared to the ASCII-art they might not be as
255comfortable for
256readers of the text files. Their advantage is that they are easy to
257create or modify and that the diff of a modification is much more meaningful,
258because it is limited to the modified content.
259
260The ``flat-table`` is a double-stage list similar to the ``list-table`` with
261some additional features:
262
263* column-span: with the role ``cspan`` a cell can be extended through
264 additional columns
265
266* row-span: with the role ``rspan`` a cell can be extended through
267 additional rows
268
269* auto span rightmost cell of a table row over the missing cells on the right
270 side of that table-row. With Option ``:fill-cells:`` this behavior can
271 changed from *auto span* to *auto fill*, which automatically inserts (empty)
272 cells instead of spanning the last cell.
273
274options:
275
276* ``:header-rows:`` [int] count of header rows
277* ``:stub-columns:`` [int] count of stub columns
278* ``:widths:`` [[int] [int] ... ] widths of columns
279* ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells
280
281roles:
282
283* ``:cspan:`` [int] additional columns (*morecols*)
284* ``:rspan:`` [int] additional rows (*morerows*)
285
286The example below shows how to use this markup. The first level of the staged
287list is the *table-row*. In the *table-row* there is only one markup allowed,
288the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
289and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
290<last row>`).
291
292.. code-block:: rst
293
294 .. flat-table:: table title
295 :widths: 2 1 1 3
296
297 * - head col 1
298 - head col 2
299 - head col 3
300 - head col 4
301
302 * - column 1
303 - field 1.1
304 - field 1.2 with autospan
305
306 * - column 2
307 - field 2.1
308 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
309
310 * .. _`last row`:
311
312 - column 3
313
314Rendered as:
315
316 .. flat-table:: table title
317 :widths: 2 1 1 3
318
319 * - head col 1
320 - head col 2
321 - head col 3
322 - head col 4
323
324 * - column 1
325 - field 1.1
326 - field 1.2 with autospan
327
328 * - column 2
329 - field 2.1
330 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
331
332 * .. _`last row`:
333
334 - column 3
335
336.. _sphinx_kfigure:
337
338Figures & Images
339================
340
341If you want to add an image, you should use the ``kernel-figure`` and
342``kernel-image`` directives. E.g. to insert a figure with a scalable
343image format use SVG (:ref:`svg_image_example`)::
344
345 .. kernel-figure:: svg_image.svg
346 :alt: simple SVG image
347
348 SVG image example
349
350.. _svg_image_example:
351
352.. kernel-figure:: svg_image.svg
353 :alt: simple SVG image
354
355 SVG image example
356
357The kernel figure (and image) directive support **DOT** formated files, see
358
359* DOT: http://graphviz.org/pdf/dotguide.pdf
360* Graphviz: http://www.graphviz.org/content/dot-language
361
362A simple example (:ref:`hello_dot_file`)::
363
364 .. kernel-figure:: hello.dot
365 :alt: hello world
366
367 DOT's hello world example
368
369.. _hello_dot_file:
370
371.. kernel-figure:: hello.dot
372 :alt: hello world
373
374 DOT's hello world example
375
376Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
377``kernel-render`` directives.::
378
379 .. kernel-render:: DOT
380 :alt: foobar digraph
381 :caption: Embedded **DOT** (Graphviz) code
382
383 digraph foo {
384 "bar" -> "baz";
385 }
386
387How this will be rendered depends on the installed tools. If Graphviz is
388installed, you will see an vector image. If not the raw markup is inserted as
389*literal-block* (:ref:`hello_dot_render`).
390
391.. _hello_dot_render:
392
393.. kernel-render:: DOT
394 :alt: foobar digraph
395 :caption: Embedded **DOT** (Graphviz) code
396
397 digraph foo {
398 "bar" -> "baz";
399 }
400
401The *render* directive has all the options known from the *figure* directive,
402plus option ``caption``. If ``caption`` has a value, a *figure* node is
403inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if
404you want to refer it (:ref:`hello_svg_render`).
405
406Embedded **SVG**::
407
408 .. kernel-render:: SVG
409 :caption: Embedded **SVG** markup
410 :alt: so-nw-arrow
411
412 <?xml version="1.0" encoding="UTF-8"?>
413 <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
414 ...
415 </svg>
416
417.. _hello_svg_render:
418
419.. kernel-render:: SVG
420 :caption: Embedded **SVG** markup
421 :alt: so-nw-arrow
422
423 <?xml version="1.0" encoding="UTF-8"?>
424 <svg xmlns="http://www.w3.org/2000/svg"
425 version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
426 <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
427 <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
428 </svg>