]>
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 | ||
22 | Sphinx Build | |
23 | ============ | |
24 | ||
25 | The usual way to generate the documentation is to run ``make htmldocs`` or | |
26 | ``make pdfdocs``. There are also other formats available, see the documentation | |
27 | section of ``make help``. The generated documentation is placed in | |
28 | format-specific subdirectories under ``Documentation/output``. | |
29 | ||
30 | To generate documentation, Sphinx (``sphinx-build``) must obviously be | |
31 | installed. For prettier HTML output, the Read the Docs Sphinx theme | |
db6ccf23 MH |
32 | (``sphinx_rtd_theme``) is used if available. For PDF output you'll also need |
33 | ``XeLaTeX`` and ``convert(1)`` from ImageMagick (https://www.imagemagick.org). | |
34 | All of these are widely available and packaged in distributions. | |
1dc4bbf0 MCC |
35 | |
36 | To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make | |
37 | variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose | |
38 | output. | |
39 | ||
40 | To remove the generated documentation, run ``make cleandocs``. | |
41 | ||
42 | Writing Documentation | |
43 | ===================== | |
44 | ||
45 | Adding new documentation can be as simple as: | |
46 | ||
47 | 1. Add a new ``.rst`` file somewhere under ``Documentation``. | |
48 | 2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``. | |
49 | ||
50 | .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html | |
51 | ||
52 | This is usually good enough for simple documentation (like the one you're | |
53 | reading right now), but for larger documents it may be advisable to create a | |
54 | subdirectory (or use an existing one). For example, the graphics subsystem | |
55 | documentation is under ``Documentation/gpu``, split to several ``.rst`` files, | |
56 | and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from | |
57 | the main index. | |
58 | ||
59 | See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do | |
60 | with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place | |
61 | to get started with reStructuredText. There are also some `Sphinx specific | |
62 | markup constructs`_. | |
63 | ||
64 | .. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html | |
65 | .. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html | |
66 | ||
67 | Specific guidelines for the kernel documentation | |
68 | ------------------------------------------------ | |
69 | ||
70 | Here are some specific guidelines for the kernel documentation: | |
71 | ||
c3c53600 DV |
72 | * Please don't go overboard with reStructuredText markup. Keep it |
73 | simple. For the most part the documentation should be plain text with | |
74 | just enough consistency in formatting that it can be converted to | |
75 | other formats. | |
76 | ||
77 | * Please keep the formatting changes minimal when converting existing | |
78 | documentation to reStructuredText. | |
79 | ||
80 | * Also update the content, not just the formatting, when converting | |
81 | documentation. | |
1dc4bbf0 MCC |
82 | |
83 | * Please stick to this order of heading adornments: | |
84 | ||
85 | 1. ``=`` with overline for document title:: | |
86 | ||
87 | ============== | |
88 | Document title | |
89 | ============== | |
90 | ||
91 | 2. ``=`` for chapters:: | |
92 | ||
93 | Chapters | |
94 | ======== | |
95 | ||
96 | 3. ``-`` for sections:: | |
97 | ||
98 | Section | |
99 | ------- | |
100 | ||
101 | 4. ``~`` for subsections:: | |
102 | ||
103 | Subsection | |
104 | ~~~~~~~~~~ | |
105 | ||
106 | Although RST doesn't mandate a specific order ("Rather than imposing a fixed | |
107 | number and order of section title adornment styles, the order enforced will be | |
108 | the order as encountered."), having the higher levels the same overall makes | |
109 | it easier to follow the documents. | |
110 | ||
c3c53600 DV |
111 | * For inserting fixed width text blocks (for code examples, use case |
112 | examples, etc.), use ``::`` for anything that doesn't really benefit | |
113 | from syntax highlighting, especially short snippets. Use | |
114 | ``.. code-block:: <language>`` for longer code blocks that benefit | |
115 | from highlighting. | |
116 | ||
1dc4bbf0 MCC |
117 | |
118 | the C domain | |
119 | ------------ | |
120 | ||
121 | The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a | |
122 | function prototype: | |
123 | ||
124 | .. code-block:: rst | |
125 | ||
126 | .. c:function:: int ioctl( int fd, int request ) | |
127 | ||
128 | The C domain of the kernel-doc has some additional features. E.g. you can | |
129 | *rename* the reference name of a function with a common name like ``open`` or | |
130 | ``ioctl``: | |
131 | ||
132 | .. code-block:: rst | |
133 | ||
134 | .. c:function:: int ioctl( int fd, int request ) | |
135 | :name: VIDIOC_LOG_STATUS | |
136 | ||
137 | The func-name (e.g. ioctl) remains in the output but the ref-name changed from | |
138 | ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also | |
139 | changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by: | |
140 | ||
141 | .. code-block:: rst | |
142 | ||
143 | :c:func:`VIDIOC_LOG_STATUS` | |
144 | ||
145 | ||
146 | list tables | |
147 | ----------- | |
148 | ||
149 | We recommend the use of *list table* formats. The *list table* formats are | |
150 | double-stage lists. Compared to the ASCII-art they might not be as | |
151 | comfortable for | |
152 | readers of the text files. Their advantage is that they are easy to | |
153 | create or modify and that the diff of a modification is much more meaningful, | |
154 | because it is limited to the modified content. | |
155 | ||
156 | The ``flat-table`` is a double-stage list similar to the ``list-table`` with | |
157 | some additional features: | |
158 | ||
159 | * column-span: with the role ``cspan`` a cell can be extended through | |
160 | additional columns | |
161 | ||
162 | * row-span: with the role ``rspan`` a cell can be extended through | |
163 | additional rows | |
164 | ||
165 | * auto span rightmost cell of a table row over the missing cells on the right | |
166 | side of that table-row. With Option ``:fill-cells:`` this behavior can | |
167 | changed from *auto span* to *auto fill*, which automatically inserts (empty) | |
168 | cells instead of spanning the last cell. | |
169 | ||
170 | options: | |
171 | ||
172 | * ``:header-rows:`` [int] count of header rows | |
173 | * ``:stub-columns:`` [int] count of stub columns | |
174 | * ``:widths:`` [[int] [int] ... ] widths of columns | |
175 | * ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells | |
176 | ||
177 | roles: | |
178 | ||
179 | * ``:cspan:`` [int] additional columns (*morecols*) | |
180 | * ``:rspan:`` [int] additional rows (*morerows*) | |
181 | ||
182 | The example below shows how to use this markup. The first level of the staged | |
183 | list is the *table-row*. In the *table-row* there is only one markup allowed, | |
184 | the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` ) | |
185 | and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row | |
186 | <last row>`). | |
187 | ||
188 | .. code-block:: rst | |
189 | ||
190 | .. flat-table:: table title | |
191 | :widths: 2 1 1 3 | |
192 | ||
193 | * - head col 1 | |
194 | - head col 2 | |
195 | - head col 3 | |
196 | - head col 4 | |
197 | ||
198 | * - column 1 | |
199 | - field 1.1 | |
200 | - field 1.2 with autospan | |
201 | ||
202 | * - column 2 | |
203 | - field 2.1 | |
204 | - :rspan:`1` :cspan:`1` field 2.2 - 3.3 | |
205 | ||
206 | * .. _`last row`: | |
207 | ||
208 | - column 3 | |
209 | ||
210 | Rendered as: | |
211 | ||
212 | .. flat-table:: table title | |
213 | :widths: 2 1 1 3 | |
214 | ||
215 | * - head col 1 | |
216 | - head col 2 | |
217 | - head col 3 | |
218 | - head col 4 | |
219 | ||
220 | * - column 1 | |
221 | - field 1.1 | |
222 | - field 1.2 with autospan | |
223 | ||
224 | * - column 2 | |
225 | - field 2.1 | |
226 | - :rspan:`1` :cspan:`1` field 2.2 - 3.3 | |
227 | ||
228 | * .. _`last row`: | |
229 | ||
230 | - column 3 | |
db6ccf23 MH |
231 | |
232 | ||
233 | Figures & Images | |
234 | ================ | |
235 | ||
236 | If you want to add an image, you should use the ``kernel-figure`` and | |
237 | ``kernel-image`` directives. E.g. to insert a figure with a scalable | |
238 | image format use SVG (:ref:`svg_image_example`):: | |
239 | ||
240 | .. kernel-figure:: svg_image.svg | |
241 | :alt: simple SVG image | |
242 | ||
243 | SVG image example | |
244 | ||
245 | .. _svg_image_example: | |
246 | ||
247 | .. kernel-figure:: svg_image.svg | |
248 | :alt: simple SVG image | |
249 | ||
250 | SVG image example | |
251 | ||
252 | The kernel figure (and image) directive support **DOT** formated files, see | |
253 | ||
254 | * DOT: http://graphviz.org/pdf/dotguide.pdf | |
255 | * Graphviz: http://www.graphviz.org/content/dot-language | |
256 | ||
257 | A simple example (:ref:`hello_dot_file`):: | |
258 | ||
259 | .. kernel-figure:: hello.dot | |
260 | :alt: hello world | |
261 | ||
262 | DOT's hello world example | |
263 | ||
264 | .. _hello_dot_file: | |
265 | ||
266 | .. kernel-figure:: hello.dot | |
267 | :alt: hello world | |
268 | ||
269 | DOT's hello world example | |
270 | ||
271 | Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the | |
272 | ``kernel-render`` directives.:: | |
273 | ||
274 | .. kernel-render:: DOT | |
275 | :alt: foobar digraph | |
276 | :caption: Embedded **DOT** (Graphviz) code | |
277 | ||
278 | digraph foo { | |
279 | "bar" -> "baz"; | |
280 | } | |
281 | ||
282 | How this will be rendered depends on the installed tools. If Graphviz is | |
283 | installed, you will see an vector image. If not the raw markup is inserted as | |
284 | *literal-block* (:ref:`hello_dot_render`). | |
285 | ||
286 | .. _hello_dot_render: | |
287 | ||
288 | .. kernel-render:: DOT | |
289 | :alt: foobar digraph | |
290 | :caption: Embedded **DOT** (Graphviz) code | |
291 | ||
292 | digraph foo { | |
293 | "bar" -> "baz"; | |
294 | } | |
295 | ||
296 | The *render* directive has all the options known from the *figure* directive, | |
297 | plus option ``caption``. If ``caption`` has a value, a *figure* node is | |
298 | inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if | |
299 | you want to refer it (:ref:`hello_svg_render`). | |
300 | ||
301 | Embedded **SVG**:: | |
302 | ||
303 | .. kernel-render:: SVG | |
304 | :caption: Embedded **SVG** markup | |
305 | :alt: so-nw-arrow | |
306 | ||
307 | <?xml version="1.0" encoding="UTF-8"?> | |
308 | <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...> | |
309 | ... | |
310 | </svg> | |
311 | ||
312 | .. _hello_svg_render: | |
313 | ||
314 | .. kernel-render:: SVG | |
315 | :caption: Embedded **SVG** markup | |
316 | :alt: so-nw-arrow | |
317 | ||
318 | <?xml version="1.0" encoding="UTF-8"?> | |
319 | <svg xmlns="http://www.w3.org/2000/svg" | |
320 | version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400"> | |
321 | <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> | |
322 | <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> | |
323 | </svg> |