Commit | Line | Data |
---|---|---|
f77af637 FV |
1 | .. _sphinxdoc: |
2 | ||
1dc4bbf0 MCC |
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 | ||
1dc4bbf0 MCC |
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 | ||
b8b07b5c MCC |
24 | .. _sphinx_install: |
25 | ||
26 | Sphinx Install | |
27 | ============== | |
28 | ||
29 | The ReST markups currently used by the Documentation/ files are meant to be | |
a700767a | 30 | built with ``Sphinx`` version 1.3 or higher. |
b8b07b5c | 31 | |
c1ec85ff | 32 | There's a script that checks for the Sphinx requirements. Please see |
868366aa MCC |
33 | :ref:`sphinx-pre-install` for further details. |
34 | ||
58ef4a42 MCC |
35 | Most distributions are shipped with Sphinx, but its toolchain is fragile, |
36 | and it is not uncommon that upgrading it or some other Python packages | |
37 | on your machine would cause the documentation build to break. | |
38 | ||
4d01460e JN |
39 | A way to avoid that is to use a different version than the one shipped |
40 | with your distributions. In order to do so, it is recommended to install | |
58ef4a42 MCC |
41 | Sphinx inside a virtual environment, using ``virtualenv-3`` |
42 | or ``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 | |
4d01460e | 47 | docutils version 0.13.1 or higher. So, if you're willing to use |
58ef4a42 MCC |
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 | ||
868366aa MCC |
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 | ||
a700767a | 58 | In summary, if you want to install Sphinx version 1.7.9, you should do:: |
58ef4a42 | 59 | |
a700767a MCC |
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 | |
58ef4a42 | 63 | |
a700767a | 64 | After running ``. sphinx_1.7.9/bin/activate``, the prompt will change, |
58ef4a42 MCC |
65 | in order to indicate that you're using the new environment. If you |
66 | open a new shell, you need to rerun this command to enter again at | |
67 | the virtual environment before building the documentation. | |
68 | ||
d43e5ae9 MCC |
69 | Image output |
70 | ------------ | |
71 | ||
72 | The kernel documentation build system contains an extension that | |
73 | handles images on both GraphViz and SVG formats (see | |
74 | :ref:`sphinx_kfigure`). | |
75 | ||
76 | For it to work, you need to install both GraphViz and ImageMagick | |
77 | packages. If those packages are not installed, the build system will | |
78 | still build the documentation, but won't include any images at the | |
79 | output. | |
80 | ||
6e322a17 MCC |
81 | PDF and LaTeX builds |
82 | -------------------- | |
83 | ||
4d01460e | 84 | Such builds are currently supported only with Sphinx versions 1.4 and higher. |
6e322a17 MCC |
85 | |
86 | For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265. | |
87 | ||
88 | Depending on the distribution, you may also need to install a series of | |
89 | ``texlive`` packages that provide the minimal set of functionalities | |
868366aa MCC |
90 | required for ``XeLaTeX`` to work. |
91 | ||
92 | .. _sphinx-pre-install: | |
93 | ||
94 | Checking for Sphinx dependencies | |
95 | -------------------------------- | |
96 | ||
97 | There's a script that automatically check for Sphinx dependencies. If it can | |
98 | recognize your distribution, it will also give a hint about the install | |
99 | command 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 | |
a700767a MCC |
107 | /usr/bin/virtualenv sphinx_1.7.9 |
108 | . sphinx_1.7.9/bin/activate | |
868366aa MCC |
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 | ||
113 | By default, it checks all the requirements for both html and PDF, including | |
114 | the requirements for images, math expressions and LaTeX build, and assumes | |
115 | that a virtual Python environment will be used. The ones needed for html | |
116 | builds are assumed to be mandatory; the others to be optional. | |
117 | ||
118 | It 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 | ||
6e322a17 | 126 | |
1dc4bbf0 MCC |
127 | Sphinx Build |
128 | ============ | |
129 | ||
130 | The usual way to generate the documentation is to run ``make htmldocs`` or | |
131 | ``make pdfdocs``. There are also other formats available, see the documentation | |
132 | section of ``make help``. The generated documentation is placed in | |
133 | format-specific subdirectories under ``Documentation/output``. | |
134 | ||
135 | To generate documentation, Sphinx (``sphinx-build``) must obviously be | |
136 | installed. For prettier HTML output, the Read the Docs Sphinx theme | |
db6ccf23 MH |
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). | |
139 | All of these are widely available and packaged in distributions. | |
1dc4bbf0 MCC |
140 | |
141 | To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make | |
142 | variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose | |
143 | output. | |
144 | ||
145 | To remove the generated documentation, run ``make cleandocs``. | |
146 | ||
147 | Writing Documentation | |
148 | ===================== | |
149 | ||
150 | Adding new documentation can be as simple as: | |
151 | ||
152 | 1. Add a new ``.rst`` file somewhere under ``Documentation``. | |
153 | 2. 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 | ||
157 | This is usually good enough for simple documentation (like the one you're | |
158 | reading right now), but for larger documents it may be advisable to create a | |
159 | subdirectory (or use an existing one). For example, the graphics subsystem | |
160 | documentation is under ``Documentation/gpu``, split to several ``.rst`` files, | |
161 | and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from | |
162 | the main index. | |
163 | ||
164 | See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do | |
165 | with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place | |
166 | to get started with reStructuredText. There are also some `Sphinx specific | |
167 | markup 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 | ||
172 | Specific guidelines for the kernel documentation | |
173 | ------------------------------------------------ | |
174 | ||
175 | Here are some specific guidelines for the kernel documentation: | |
176 | ||
c3c53600 DV |
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. | |
1dc4bbf0 MCC |
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 | ||
c3c53600 DV |
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 | |
83e8b971 | 220 | from highlighting. For a short snippet of code embedded in the text, use \`\`. |
c3c53600 | 221 | |
1dc4bbf0 MCC |
222 | |
223 | the C domain | |
224 | ------------ | |
225 | ||
29fd35bd | 226 | The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a |
1dc4bbf0 MCC |
227 | function prototype: |
228 | ||
229 | .. code-block:: rst | |
230 | ||
231 | .. c:function:: int ioctl( int fd, int request ) | |
232 | ||
233 | The 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 | ||
242 | The 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 | |
d9d7c0c4 JC |
244 | changed to ``VIDIOC_LOG_STATUS``. |
245 | ||
246 | Please note that there is no need to use ``c:func:`` to generate cross | |
247 | references to function documentation. Due to some Sphinx extension magic, | |
248 | the documentation build system will automatically turn a reference to | |
249 | ``function()`` into a cross reference if an index entry for the given | |
250 | function name exists. If you see ``c:func:`` use in a kernel document, | |
251 | please feel free to remove it. | |
1dc4bbf0 MCC |
252 | |
253 | ||
254 | list tables | |
255 | ----------- | |
256 | ||
257 | We recommend the use of *list table* formats. The *list table* formats are | |
258 | double-stage lists. Compared to the ASCII-art they might not be as | |
259 | comfortable for | |
260 | readers of the text files. Their advantage is that they are easy to | |
261 | create or modify and that the diff of a modification is much more meaningful, | |
262 | because it is limited to the modified content. | |
263 | ||
264 | The ``flat-table`` is a double-stage list similar to the ``list-table`` with | |
265 | some 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 | ||
278 | options: | |
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 | ||
285 | roles: | |
286 | ||
287 | * ``:cspan:`` [int] additional columns (*morecols*) | |
288 | * ``:rspan:`` [int] additional rows (*morerows*) | |
289 | ||
290 | The example below shows how to use this markup. The first level of the staged | |
291 | list is the *table-row*. In the *table-row* there is only one markup allowed, | |
292 | the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` ) | |
293 | and *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 | ||
318 | Rendered 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 | |
db6ccf23 | 339 | |
d43e5ae9 | 340 | .. _sphinx_kfigure: |
db6ccf23 MH |
341 | |
342 | Figures & Images | |
343 | ================ | |
344 | ||
345 | If you want to add an image, you should use the ``kernel-figure`` and | |
346 | ``kernel-image`` directives. E.g. to insert a figure with a scalable | |
347 | image format use SVG (:ref:`svg_image_example`):: | |
348 | ||
349 | .. kernel-figure:: svg_image.svg | |
350 | :alt: simple SVG image | |
351 | ||
352 | SVG image example | |
353 | ||
354 | .. _svg_image_example: | |
355 | ||
356 | .. kernel-figure:: svg_image.svg | |
357 | :alt: simple SVG image | |
358 | ||
359 | SVG image example | |
360 | ||
361 | The kernel figure (and image) directive support **DOT** formated files, see | |
362 | ||
363 | * DOT: http://graphviz.org/pdf/dotguide.pdf | |
364 | * Graphviz: http://www.graphviz.org/content/dot-language | |
365 | ||
366 | A simple example (:ref:`hello_dot_file`):: | |
367 | ||
368 | .. kernel-figure:: hello.dot | |
369 | :alt: hello world | |
370 | ||
371 | DOT's hello world example | |
372 | ||
373 | .. _hello_dot_file: | |
374 | ||
375 | .. kernel-figure:: hello.dot | |
376 | :alt: hello world | |
377 | ||
378 | DOT's hello world example | |
379 | ||
380 | Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the | |
381 | ``kernel-render`` directives.:: | |
382 | ||
383 | .. kernel-render:: DOT | |
384 | :alt: foobar digraph | |
385 | :caption: Embedded **DOT** (Graphviz) code | |
386 | ||
387 | digraph foo { | |
388 | "bar" -> "baz"; | |
389 | } | |
390 | ||
391 | How this will be rendered depends on the installed tools. If Graphviz is | |
392 | installed, you will see an vector image. If not the raw markup is inserted as | |
393 | *literal-block* (:ref:`hello_dot_render`). | |
394 | ||
395 | .. _hello_dot_render: | |
396 | ||
397 | .. kernel-render:: DOT | |
398 | :alt: foobar digraph | |
399 | :caption: Embedded **DOT** (Graphviz) code | |
400 | ||
401 | digraph foo { | |
402 | "bar" -> "baz"; | |
403 | } | |
404 | ||
405 | The *render* directive has all the options known from the *figure* directive, | |
406 | plus option ``caption``. If ``caption`` has a value, a *figure* node is | |
407 | inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if | |
408 | you want to refer it (:ref:`hello_svg_render`). | |
409 | ||
410 | Embedded **SVG**:: | |
411 | ||
412 | .. kernel-render:: SVG | |
413 | :caption: Embedded **SVG** markup | |
414 | :alt: so-nw-arrow | |
415 | ||
416 | <?xml version="1.0" encoding="UTF-8"?> | |
417 | <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...> | |
418 | ... | |
419 | </svg> | |
420 | ||
421 | .. _hello_svg_render: | |
422 | ||
423 | .. kernel-render:: SVG | |
424 | :caption: Embedded **SVG** markup | |
425 | :alt: so-nw-arrow | |
426 | ||
427 | <?xml version="1.0" encoding="UTF-8"?> | |
428 | <svg xmlns="http://www.w3.org/2000/svg" | |
429 | version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400"> | |
430 | <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> | |
431 | <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> | |
432 | </svg> |