blob: 84e8e8a9cbdb0431ef2e67fca56b39475a633e5e [file] [log] [blame]
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -02001Introduction
2============
3
4The Linux kernel uses `Sphinx`_ to generate pretty documentation from
5`reStructuredText`_ files under ``Documentation``. To build the documentation in
6HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated
7documentation is placed in ``Documentation/output``.
8
9.. _Sphinx: http://www.sphinx-doc.org/
10.. _reStructuredText: http://docutils.sourceforge.net/rst.html
11
12The reStructuredText files may contain directives to include structured
13documentation comments, or kernel-doc comments, from source files. Usually these
14are used to describe the functions and types and design of the code. The
15kernel-doc comments have some special structure and formatting, but beyond that
16they are also treated as reStructuredText.
17
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -020018Finally, there are thousands of plain text documentation files scattered around
19``Documentation``. Some of these will likely be converted to reStructuredText
20over time, but the bulk of them will remain in plain text.
21
22Sphinx Build
23============
24
25The usual way to generate the documentation is to run ``make htmldocs`` or
26``make pdfdocs``. There are also other formats available, see the documentation
27section of ``make help``. The generated documentation is placed in
28format-specific subdirectories under ``Documentation/output``.
29
30To generate documentation, Sphinx (``sphinx-build``) must obviously be
31installed. For prettier HTML output, the Read the Docs Sphinx theme
Markus Heiserdb6ccf22017-03-06 14:09:27 +010032(``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).
34All of these are widely available and packaged in distributions.
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -020035
36To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
37variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
38output.
39
40To remove the generated documentation, run ``make cleandocs``.
41
42Writing Documentation
43=====================
44
45Adding new documentation can be as simple as:
46
471. Add a new ``.rst`` file somewhere under ``Documentation``.
482. 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
52This is usually good enough for simple documentation (like the one you're
53reading right now), but for larger documents it may be advisable to create a
54subdirectory (or use an existing one). For example, the graphics subsystem
55documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
56and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
57the main index.
58
59See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
60with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
61to get started with reStructuredText. There are also some `Sphinx specific
62markup 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
67Specific guidelines for the kernel documentation
68------------------------------------------------
69
70Here are some specific guidelines for the kernel documentation:
71
Daniel Vetterc3c53602017-03-02 16:16:33 +010072* 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.
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -020082
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
Daniel Vetterc3c53602017-03-02 16:16:33 +0100111* 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
Mauro Carvalho Chehab1dc4bbf2016-11-17 08:32:33 -0200117
118the C domain
119------------
120
121The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a
122function prototype:
123
124.. code-block:: rst
125
126 .. c:function:: int ioctl( int fd, int request )
127
128The 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
137The 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
139changed 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
146list tables
147-----------
148
149We recommend the use of *list table* formats. The *list table* formats are
150double-stage lists. Compared to the ASCII-art they might not be as
151comfortable for
152readers of the text files. Their advantage is that they are easy to
153create or modify and that the diff of a modification is much more meaningful,
154because it is limited to the modified content.
155
156The ``flat-table`` is a double-stage list similar to the ``list-table`` with
157some 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
170options:
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
177roles:
178
179* ``:cspan:`` [int] additional columns (*morecols*)
180* ``:rspan:`` [int] additional rows (*morerows*)
181
182The example below shows how to use this markup. The first level of the staged
183list is the *table-row*. In the *table-row* there is only one markup allowed,
184the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
185and *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
210Rendered 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
Markus Heiserdb6ccf22017-03-06 14:09:27 +0100231
232
233Figures & Images
234================
235
236If 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
238image 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
252The 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
257A 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
271Embed *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
282How this will be rendered depends on the installed tools. If Graphviz is
283installed, 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
296The *render* directive has all the options known from the *figure* directive,
297plus option ``caption``. If ``caption`` has a value, a *figure* node is
298inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if
299you want to refer it (:ref:`hello_svg_render`).
300
301Embedded **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>