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 | |
30 | built with ``Sphinx`` version 1.3 or upper. If you're desiring to build | |
31 | PDF outputs, it is recommended to use version 1.4.6 or upper. | |
32 | ||
c1ec85ff | 33 | There's a script that checks for the Sphinx requirements. Please see |
868366aa MCC |
34 | :ref:`sphinx-pre-install` for further details. |
35 | ||
58ef4a42 MCC |
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 get rid of that is to use a different version than the one shipped | |
41 | on your distributions. In order to do that, 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 upper. 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 | ||
868366aa MCC |
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 | ||
58ef4a42 MCC |
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 | |
868366aa | 63 | (sphinx_1.4) $ pip install -r Documentation/sphinx/requirements.txt |
58ef4a42 MCC |
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 | ||
d43e5ae9 MCC |
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 | ||
6e322a17 MCC |
82 | PDF and LaTeX builds |
83 | -------------------- | |
84 | ||
95a40b86 | 85 | Such builds are currently supported only with Sphinx versions 1.4 and upper. |
6e322a17 MCC |
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 | |
868366aa MCC |
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 | ||
6e322a17 | 127 | |
1dc4bbf0 MCC |
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 | |
db6ccf23 MH |
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. | |
1dc4bbf0 MCC |
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 | ||
c3c53600 DV |
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. | |
1dc4bbf0 MCC |
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 | ||
c3c53600 DV |
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 | ||
1dc4bbf0 MCC |
223 | |
224 | the C domain | |
225 | ------------ | |
226 | ||
29fd35bd | 227 | The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a |
1dc4bbf0 MCC |
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 | |
db6ccf23 | 337 | |
d43e5ae9 | 338 | .. _sphinx_kfigure: |
db6ccf23 MH |
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> |