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