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, ``rst2pdf`` is also 38needed. All of these are widely available and packaged in distributions. 39 40To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make 41variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose 42output. 43 44To remove the generated documentation, run ``make cleandocs``. 45 46Writing Documentation 47===================== 48 49Adding new documentation can be as simple as: 50 511. Add a new ``.rst`` file somewhere under ``Documentation``. 522. 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 56This is usually good enough for simple documentation (like the one you're 57reading right now), but for larger documents it may be advisable to create a 58subdirectory (or use an existing one). For example, the graphics subsystem 59documentation is under ``Documentation/gpu``, split to several ``.rst`` files, 60and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from 61the main index. 62 63See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do 64with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place 65to get started with reStructuredText. There are also some `Sphinx specific 66markup 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 71Specific guidelines for the kernel documentation 72------------------------------------------------ 73 74Here 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 107the C domain 108------------ 109 110The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a 111function prototype: 112 113.. code-block:: rst 114 115 .. c:function:: int ioctl( int fd, int request ) 116 117The 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 126The 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 128changed 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 135list tables 136----------- 137 138We recommend the use of *list table* formats. The *list table* formats are 139double-stage lists. Compared to the ASCII-art they might not be as 140comfortable for 141readers of the text files. Their advantage is that they are easy to 142create or modify and that the diff of a modification is much more meaningful, 143because it is limited to the modified content. 144 145The ``flat-table`` is a double-stage list similar to the ``list-table`` with 146some 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 159options: 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 166roles: 167 168* ``:cspan:`` [int] additional columns (*morecols*) 169* ``:rspan:`` [int] additional rows (*morerows*) 170 171The example below shows how to use this markup. The first level of the staged 172list is the *table-row*. In the *table-row* there is only one markup allowed, 173the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` ) 174and *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 199Rendered 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 220