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  in separate,
52      with ``pip install sphinx_rtd_theme``.
53
54   #) Some ReST pages contain math expressions. Due to the way Sphinx work,
55      those expressions are written using LaTeX notation. It needs texlive
56      installed with amdfonts 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      * - column 1
307        - field 1.1
308        - field 1.2 with autospan
309
310      * - column 2
311        - field 2.1
312        - :rspan:`1` :cspan:`1` field 2.2 - 3.3
313
314      * .. _`last row`:
315
316        - column 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      * - column 1
329        - field 1.1
330        - field 1.2 with autospan
331
332      * - column 2
333        - field 2.1
334        - :rspan:`1` :cspan:`1` field 2.2 - 3.3
335
336      * .. _`last row`:
337
338        - column 3
339
340Cross-referencing
341-----------------
342
343Cross-referencing from one documentation page to another can be done by passing
344the path to the file starting from the Documentation folder.
345For example, to cross-reference to this page (the .rst extension is optional)::
346
347    See Documentation/doc-guide/sphinx.rst.
348
349If you want to use a relative path, you need to use Sphinx's ``doc`` directive.
350For example, referencing this page from the same directory would be done as::
351
352    See :doc:`sphinx`.
353
354For information on cross-referencing to kernel-doc functions or types, see
355Documentation/doc-guide/kernel-doc.rst.
356
357.. _sphinx_kfigure:
358
359Figures & Images
360================
361
362If you want to add an image, you should use the ``kernel-figure`` and
363``kernel-image`` directives. E.g. to insert a figure with a scalable
364image format use SVG (:ref:`svg_image_example`)::
365
366    .. kernel-figure::  svg_image.svg
367       :alt:    simple SVG image
368
369       SVG image example
370
371.. _svg_image_example:
372
373.. kernel-figure::  svg_image.svg
374   :alt:    simple SVG image
375
376   SVG image example
377
378The kernel figure (and image) directive support **DOT** formated files, see
379
380* DOT: http://graphviz.org/pdf/dotguide.pdf
381* Graphviz: http://www.graphviz.org/content/dot-language
382
383A simple example (:ref:`hello_dot_file`)::
384
385  .. kernel-figure::  hello.dot
386     :alt:    hello world
387
388     DOT's hello world example
389
390.. _hello_dot_file:
391
392.. kernel-figure::  hello.dot
393   :alt:    hello world
394
395   DOT's hello world example
396
397Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
398``kernel-render`` directives.::
399
400  .. kernel-render:: DOT
401     :alt: foobar digraph
402     :caption: Embedded **DOT** (Graphviz) code
403
404     digraph foo {
405      "bar" -> "baz";
406     }
407
408How this will be rendered depends on the installed tools. If Graphviz is
409installed, you will see an vector image. If not the raw markup is inserted as
410*literal-block* (:ref:`hello_dot_render`).
411
412.. _hello_dot_render:
413
414.. kernel-render:: DOT
415   :alt: foobar digraph
416   :caption: Embedded **DOT** (Graphviz) code
417
418   digraph foo {
419      "bar" -> "baz";
420   }
421
422The *render* directive has all the options known from the *figure* directive,
423plus option ``caption``.  If ``caption`` has a value, a *figure* node is
424inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if
425you want to refer it (:ref:`hello_svg_render`).
426
427Embedded **SVG**::
428
429  .. kernel-render:: SVG
430     :caption: Embedded **SVG** markup
431     :alt: so-nw-arrow
432
433     <?xml version="1.0" encoding="UTF-8"?>
434     <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
435        ...
436     </svg>
437
438.. _hello_svg_render:
439
440.. kernel-render:: SVG
441   :caption: Embedded **SVG** markup
442   :alt: so-nw-arrow
443
444   <?xml version="1.0" encoding="UTF-8"?>
445   <svg xmlns="http://www.w3.org/2000/svg"
446     version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
447   <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
448   <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
449   </svg>
450