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