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