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