]>
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 | ||
18 | There is also the deprecated DocBook toolchain to generate documentation from | |
19 | DocBook XML template files under ``Documentation/DocBook``. The DocBook files | |
20 | are to be converted to reStructuredText, and the toolchain is slated to be | |
21 | removed. | |
22 | ||
23 | Finally, there are thousands of plain text documentation files scattered around | |
24 | ``Documentation``. Some of these will likely be converted to reStructuredText | |
25 | over time, but the bulk of them will remain in plain text. | |
26 | ||
27 | Sphinx Build | |
28 | ============ | |
29 | ||
30 | The usual way to generate the documentation is to run ``make htmldocs`` or | |
31 | ``make pdfdocs``. There are also other formats available, see the documentation | |
32 | section of ``make help``. The generated documentation is placed in | |
33 | format-specific subdirectories under ``Documentation/output``. | |
34 | ||
35 | To generate documentation, Sphinx (``sphinx-build``) must obviously be | |
36 | installed. For prettier HTML output, the Read the Docs Sphinx theme | |
37 | (``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is also | |
38 | needed. All of these are widely available and packaged in distributions. | |
39 | ||
40 | To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make | |
41 | variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose | |
42 | output. | |
43 | ||
44 | To remove the generated documentation, run ``make cleandocs``. | |
45 | ||
46 | Writing Documentation | |
47 | ===================== | |
48 | ||
49 | Adding new documentation can be as simple as: | |
50 | ||
51 | 1. Add a new ``.rst`` file somewhere under ``Documentation``. | |
52 | 2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``. | |
53 | ||
54 | .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html | |
55 | ||
56 | This is usually good enough for simple documentation (like the one you're | |
57 | reading right now), but for larger documents it may be advisable to create a | |
58 | subdirectory (or use an existing one). For example, the graphics subsystem | |
59 | documentation is under ``Documentation/gpu``, split to several ``.rst`` files, | |
60 | and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from | |
61 | the main index. | |
62 | ||
63 | See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do | |
64 | with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place | |
65 | to get started with reStructuredText. There are also some `Sphinx specific | |
66 | markup constructs`_. | |
67 | ||
68 | .. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html | |
69 | .. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html | |
70 | ||
71 | Specific guidelines for the kernel documentation | |
72 | ------------------------------------------------ | |
73 | ||
74 | Here are some specific guidelines for the kernel documentation: | |
75 | ||
76 | * Please don't go overboard with reStructuredText markup. Keep it simple. | |
77 | ||
78 | * Please stick to this order of heading adornments: | |
79 | ||
80 | 1. ``=`` with overline for document title:: | |
81 | ||
82 | ============== | |
83 | Document title | |
84 | ============== | |
85 | ||
86 | 2. ``=`` for chapters:: | |
87 | ||
88 | Chapters | |
89 | ======== | |
90 | ||
91 | 3. ``-`` for sections:: | |
92 | ||
93 | Section | |
94 | ------- | |
95 | ||
96 | 4. ``~`` for subsections:: | |
97 | ||
98 | Subsection | |
99 | ~~~~~~~~~~ | |
100 | ||
101 | Although RST doesn't mandate a specific order ("Rather than imposing a fixed | |
102 | number and order of section title adornment styles, the order enforced will be | |
103 | the order as encountered."), having the higher levels the same overall makes | |
104 | it easier to follow the documents. | |
105 | ||
106 | ||
107 | the C domain | |
108 | ------------ | |
109 | ||
110 | The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a | |
111 | function prototype: | |
112 | ||
113 | .. code-block:: rst | |
114 | ||
115 | .. c:function:: int ioctl( int fd, int request ) | |
116 | ||
117 | The C domain of the kernel-doc has some additional features. E.g. you can | |
118 | *rename* the reference name of a function with a common name like ``open`` or | |
119 | ``ioctl``: | |
120 | ||
121 | .. code-block:: rst | |
122 | ||
123 | .. c:function:: int ioctl( int fd, int request ) | |
124 | :name: VIDIOC_LOG_STATUS | |
125 | ||
126 | The func-name (e.g. ioctl) remains in the output but the ref-name changed from | |
127 | ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also | |
128 | changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by: | |
129 | ||
130 | .. code-block:: rst | |
131 | ||
132 | :c:func:`VIDIOC_LOG_STATUS` | |
133 | ||
134 | ||
135 | list tables | |
136 | ----------- | |
137 | ||
138 | We recommend the use of *list table* formats. The *list table* formats are | |
139 | double-stage lists. Compared to the ASCII-art they might not be as | |
140 | comfortable for | |
141 | readers of the text files. Their advantage is that they are easy to | |
142 | create or modify and that the diff of a modification is much more meaningful, | |
143 | because it is limited to the modified content. | |
144 | ||
145 | The ``flat-table`` is a double-stage list similar to the ``list-table`` with | |
146 | some additional features: | |
147 | ||
148 | * column-span: with the role ``cspan`` a cell can be extended through | |
149 | additional columns | |
150 | ||
151 | * row-span: with the role ``rspan`` a cell can be extended through | |
152 | additional rows | |
153 | ||
154 | * auto span rightmost cell of a table row over the missing cells on the right | |
155 | side of that table-row. With Option ``:fill-cells:`` this behavior can | |
156 | changed from *auto span* to *auto fill*, which automatically inserts (empty) | |
157 | cells instead of spanning the last cell. | |
158 | ||
159 | options: | |
160 | ||
161 | * ``:header-rows:`` [int] count of header rows | |
162 | * ``:stub-columns:`` [int] count of stub columns | |
163 | * ``:widths:`` [[int] [int] ... ] widths of columns | |
164 | * ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells | |
165 | ||
166 | roles: | |
167 | ||
168 | * ``:cspan:`` [int] additional columns (*morecols*) | |
169 | * ``:rspan:`` [int] additional rows (*morerows*) | |
170 | ||
171 | The example below shows how to use this markup. The first level of the staged | |
172 | list is the *table-row*. In the *table-row* there is only one markup allowed, | |
173 | the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` ) | |
174 | and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row | |
175 | <last row>`). | |
176 | ||
177 | .. code-block:: rst | |
178 | ||
179 | .. flat-table:: table title | |
180 | :widths: 2 1 1 3 | |
181 | ||
182 | * - head col 1 | |
183 | - head col 2 | |
184 | - head col 3 | |
185 | - head col 4 | |
186 | ||
187 | * - column 1 | |
188 | - field 1.1 | |
189 | - field 1.2 with autospan | |
190 | ||
191 | * - column 2 | |
192 | - field 2.1 | |
193 | - :rspan:`1` :cspan:`1` field 2.2 - 3.3 | |
194 | ||
195 | * .. _`last row`: | |
196 | ||
197 | - column 3 | |
198 | ||
199 | Rendered as: | |
200 | ||
201 | .. flat-table:: table title | |
202 | :widths: 2 1 1 3 | |
203 | ||
204 | * - head col 1 | |
205 | - head col 2 | |
206 | - head col 3 | |
207 | - head col 4 | |
208 | ||
209 | * - column 1 | |
210 | - field 1.1 | |
211 | - field 1.2 with autospan | |
212 | ||
213 | * - column 2 | |
214 | - field 2.1 | |
215 | - :rspan:`1` :cspan:`1` field 2.2 - 3.3 | |
216 | ||
217 | * .. _`last row`: | |
218 | ||
219 | - column 3 |