1Introduction 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 18Finally, 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 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). 34All of these are widely available and packaged in distributions. 35 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 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. 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 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 117 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 231 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> 324
