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