1.. _sphinxdoc: 2 3Introduction 4============ 5 6The Linux kernel uses `Sphinx`_ to generate pretty documentation from 7`reStructuredText`_ files under ``Documentation``. To build the documentation in 8HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated 9documentation is placed in ``Documentation/output``. 10 11.. _Sphinx: http://www.sphinx-doc.org/ 12.. _reStructuredText: http://docutils.sourceforge.net/rst.html 13 14The reStructuredText files may contain directives to include structured 15documentation comments, or kernel-doc comments, from source files. Usually these 16are used to describe the functions and types and design of the code. The 17kernel-doc comments have some special structure and formatting, but beyond that 18they are also treated as reStructuredText. 19 20Finally, there are thousands of plain text documentation files scattered around 21``Documentation``. Some of these will likely be converted to reStructuredText 22over time, but the bulk of them will remain in plain text. 23 24.. _sphinx_install: 25 26Sphinx Install 27============== 28 29The ReST markups currently used by the Documentation/ files are meant to be 30built with ``Sphinx`` version 1.3 or higher. 31 32There's a script that checks for the Sphinx requirements. Please see 33:ref:`sphinx-pre-install` for further details. 34 35Most distributions are shipped with Sphinx, but its toolchain is fragile, 36and it is not uncommon that upgrading it or some other Python packages 37on your machine would cause the documentation build to break. 38 39A way to avoid that is to use a different version than the one shipped 40with your distributions. In order to do so, it is recommended to install 41Sphinx inside a virtual environment, using ``virtualenv-3`` 42or ``virtualenv``, depending on how your distribution packaged Python 3. 43 44.. note:: 45 46 #) Sphinx versions below 1.5 don't work properly with Python's 47 docutils version 0.13.1 or higher. So, if you're willing to use 48 those versions, you should run ``pip install 'docutils==0.12'``. 49 50 #) It is recommended to use the RTD theme for html output. Depending 51 on the Sphinx version, it should be installed in separate, 52 with ``pip install sphinx_rtd_theme``. 53 54 #) Some ReST pages contain math expressions. Due to the way Sphinx work, 55 those expressions are written using LaTeX notation. It needs texlive 56 installed with amdfonts and amsmath in order to evaluate them. 57 58In summary, if you want to install Sphinx version 1.7.9, you should do:: 59 60 $ virtualenv sphinx_1.7.9 61 $ . sphinx_1.7.9/bin/activate 62 (sphinx_1.7.9) $ pip install -r Documentation/sphinx/requirements.txt 63 64After running ``. sphinx_1.7.9/bin/activate``, the prompt will change, 65in order to indicate that you're using the new environment. If you 66open a new shell, you need to rerun this command to enter again at 67the virtual environment before building the documentation. 68 69Image output 70------------ 71 72The kernel documentation build system contains an extension that 73handles images on both GraphViz and SVG formats (see 74:ref:`sphinx_kfigure`). 75 76For it to work, you need to install both GraphViz and ImageMagick 77packages. If those packages are not installed, the build system will 78still build the documentation, but won't include any images at the 79output. 80 81PDF and LaTeX builds 82-------------------- 83 84Such builds are currently supported only with Sphinx versions 1.4 and higher. 85 86For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265. 87 88Depending on the distribution, you may also need to install a series of 89``texlive`` packages that provide the minimal set of functionalities 90required for ``XeLaTeX`` to work. 91 92.. _sphinx-pre-install: 93 94Checking for Sphinx dependencies 95-------------------------------- 96 97There's a script that automatically check for Sphinx dependencies. If it can 98recognize your distribution, it will also give a hint about the install 99command line options for your distro:: 100 101 $ ./scripts/sphinx-pre-install 102 Checking if the needed tools for Fedora release 26 (Twenty Six) are available 103 Warning: better to also install "texlive-luatex85". 104 You should run: 105 106 sudo dnf install -y texlive-luatex85 107 /usr/bin/virtualenv sphinx_1.7.9 108 . sphinx_1.7.9/bin/activate 109 pip install -r Documentation/sphinx/requirements.txt 110 111 Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468. 112 113By default, it checks all the requirements for both html and PDF, including 114the requirements for images, math expressions and LaTeX build, and assumes 115that a virtual Python environment will be used. The ones needed for html 116builds are assumed to be mandatory; the others to be optional. 117 118It supports two optional parameters: 119 120``--no-pdf`` 121 Disable checks for PDF; 122 123``--no-virtualenv`` 124 Use OS packaging for Sphinx instead of Python virtual environment. 125 126 127Sphinx Build 128============ 129 130The usual way to generate the documentation is to run ``make htmldocs`` or 131``make pdfdocs``. There are also other formats available, see the documentation 132section of ``make help``. The generated documentation is placed in 133format-specific subdirectories under ``Documentation/output``. 134 135To generate documentation, Sphinx (``sphinx-build``) must obviously be 136installed. For prettier HTML output, the Read the Docs Sphinx theme 137(``sphinx_rtd_theme``) is used if available. For PDF output you'll also need 138``XeLaTeX`` and ``convert(1)`` from ImageMagick (https://www.imagemagick.org). 139All of these are widely available and packaged in distributions. 140 141To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make 142variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose 143output. 144 145To remove the generated documentation, run ``make cleandocs``. 146 147Writing Documentation 148===================== 149 150Adding new documentation can be as simple as: 151 1521. Add a new ``.rst`` file somewhere under ``Documentation``. 1532. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``. 154 155.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html 156 157This is usually good enough for simple documentation (like the one you're 158reading right now), but for larger documents it may be advisable to create a 159subdirectory (or use an existing one). For example, the graphics subsystem 160documentation is under ``Documentation/gpu``, split to several ``.rst`` files, 161and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from 162the main index. 163 164See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do 165with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place 166to get started with reStructuredText. There are also some `Sphinx specific 167markup constructs`_. 168 169.. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html 170.. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html 171 172Specific guidelines for the kernel documentation 173------------------------------------------------ 174 175Here are some specific guidelines for the kernel documentation: 176 177* Please don't go overboard with reStructuredText markup. Keep it 178 simple. For the most part the documentation should be plain text with 179 just enough consistency in formatting that it can be converted to 180 other formats. 181 182* Please keep the formatting changes minimal when converting existing 183 documentation to reStructuredText. 184 185* Also update the content, not just the formatting, when converting 186 documentation. 187 188* Please stick to this order of heading adornments: 189 190 1. ``=`` with overline for document title:: 191 192 ============== 193 Document title 194 ============== 195 196 2. ``=`` for chapters:: 197 198 Chapters 199 ======== 200 201 3. ``-`` for sections:: 202 203 Section 204 ------- 205 206 4. ``~`` for subsections:: 207 208 Subsection 209 ~~~~~~~~~~ 210 211 Although RST doesn't mandate a specific order ("Rather than imposing a fixed 212 number and order of section title adornment styles, the order enforced will be 213 the order as encountered."), having the higher levels the same overall makes 214 it easier to follow the documents. 215 216* For inserting fixed width text blocks (for code examples, use case 217 examples, etc.), use ``::`` for anything that doesn't really benefit 218 from syntax highlighting, especially short snippets. Use 219 ``.. code-block:: <language>`` for longer code blocks that benefit 220 from highlighting. For a short snippet of code embedded in the text, use \`\`. 221 222 223the C domain 224------------ 225 226The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a 227function prototype: 228 229.. code-block:: rst 230 231 .. c:function:: int ioctl( int fd, int request ) 232 233The C domain of the kernel-doc has some additional features. E.g. you can 234*rename* the reference name of a function with a common name like ``open`` or 235``ioctl``: 236 237.. code-block:: rst 238 239 .. c:function:: int ioctl( int fd, int request ) 240 :name: VIDIOC_LOG_STATUS 241 242The func-name (e.g. ioctl) remains in the output but the ref-name changed from 243``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also 244changed to ``VIDIOC_LOG_STATUS``. 245 246Please note that there is no need to use ``c:func:`` to generate cross 247references to function documentation. Due to some Sphinx extension magic, 248the documentation build system will automatically turn a reference to 249``function()`` into a cross reference if an index entry for the given 250function name exists. If you see ``c:func:`` use in a kernel document, 251please feel free to remove it. 252 253 254list tables 255----------- 256 257We recommend the use of *list table* formats. The *list table* formats are 258double-stage lists. Compared to the ASCII-art they might not be as 259comfortable for 260readers of the text files. Their advantage is that they are easy to 261create or modify and that the diff of a modification is much more meaningful, 262because it is limited to the modified content. 263 264The ``flat-table`` is a double-stage list similar to the ``list-table`` with 265some additional features: 266 267* column-span: with the role ``cspan`` a cell can be extended through 268 additional columns 269 270* row-span: with the role ``rspan`` a cell can be extended through 271 additional rows 272 273* auto span rightmost cell of a table row over the missing cells on the right 274 side of that table-row. With Option ``:fill-cells:`` this behavior can 275 changed from *auto span* to *auto fill*, which automatically inserts (empty) 276 cells instead of spanning the last cell. 277 278options: 279 280* ``:header-rows:`` [int] count of header rows 281* ``:stub-columns:`` [int] count of stub columns 282* ``:widths:`` [[int] [int] ... ] widths of columns 283* ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells 284 285roles: 286 287* ``:cspan:`` [int] additional columns (*morecols*) 288* ``:rspan:`` [int] additional rows (*morerows*) 289 290The example below shows how to use this markup. The first level of the staged 291list is the *table-row*. In the *table-row* there is only one markup allowed, 292the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` ) 293and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row 294<last row>`). 295 296.. code-block:: rst 297 298 .. flat-table:: table title 299 :widths: 2 1 1 3 300 301 * - head col 1 302 - head col 2 303 - head col 3 304 - head col 4 305 306 * - column 1 307 - field 1.1 308 - field 1.2 with autospan 309 310 * - column 2 311 - field 2.1 312 - :rspan:`1` :cspan:`1` field 2.2 - 3.3 313 314 * .. _`last row`: 315 316 - column 3 317 318Rendered as: 319 320 .. flat-table:: table title 321 :widths: 2 1 1 3 322 323 * - head col 1 324 - head col 2 325 - head col 3 326 - head col 4 327 328 * - column 1 329 - field 1.1 330 - field 1.2 with autospan 331 332 * - column 2 333 - field 2.1 334 - :rspan:`1` :cspan:`1` field 2.2 - 3.3 335 336 * .. _`last row`: 337 338 - column 3 339 340Cross-referencing 341----------------- 342 343Cross-referencing from one documentation page to another can be done by passing 344the path to the file starting from the Documentation folder. 345For example, to cross-reference to this page (the .rst extension is optional):: 346 347 See Documentation/doc-guide/sphinx.rst. 348 349If you want to use a relative path, you need to use Sphinx's ``doc`` directive. 350For example, referencing this page from the same directory would be done as:: 351 352 See :doc:`sphinx`. 353 354For information on cross-referencing to kernel-doc functions or types, see 355Documentation/doc-guide/kernel-doc.rst. 356 357.. _sphinx_kfigure: 358 359Figures & Images 360================ 361 362If you want to add an image, you should use the ``kernel-figure`` and 363``kernel-image`` directives. E.g. to insert a figure with a scalable 364image format use SVG (:ref:`svg_image_example`):: 365 366 .. kernel-figure:: svg_image.svg 367 :alt: simple SVG image 368 369 SVG image example 370 371.. _svg_image_example: 372 373.. kernel-figure:: svg_image.svg 374 :alt: simple SVG image 375 376 SVG image example 377 378The kernel figure (and image) directive support **DOT** formatted files, see 379 380* DOT: http://graphviz.org/pdf/dotguide.pdf 381* Graphviz: http://www.graphviz.org/content/dot-language 382 383A simple example (:ref:`hello_dot_file`):: 384 385 .. kernel-figure:: hello.dot 386 :alt: hello world 387 388 DOT's hello world example 389 390.. _hello_dot_file: 391 392.. kernel-figure:: hello.dot 393 :alt: hello world 394 395 DOT's hello world example 396 397Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the 398``kernel-render`` directives.:: 399 400 .. kernel-render:: DOT 401 :alt: foobar digraph 402 :caption: Embedded **DOT** (Graphviz) code 403 404 digraph foo { 405 "bar" -> "baz"; 406 } 407 408How this will be rendered depends on the installed tools. If Graphviz is 409installed, you will see an vector image. If not the raw markup is inserted as 410*literal-block* (:ref:`hello_dot_render`). 411 412.. _hello_dot_render: 413 414.. kernel-render:: DOT 415 :alt: foobar digraph 416 :caption: Embedded **DOT** (Graphviz) code 417 418 digraph foo { 419 "bar" -> "baz"; 420 } 421 422The *render* directive has all the options known from the *figure* directive, 423plus option ``caption``. If ``caption`` has a value, a *figure* node is 424inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if 425you want to refer it (:ref:`hello_svg_render`). 426 427Embedded **SVG**:: 428 429 .. kernel-render:: SVG 430 :caption: Embedded **SVG** markup 431 :alt: so-nw-arrow 432 433 <?xml version="1.0" encoding="UTF-8"?> 434 <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...> 435 ... 436 </svg> 437 438.. _hello_svg_render: 439 440.. kernel-render:: SVG 441 :caption: Embedded **SVG** markup 442 :alt: so-nw-arrow 443 444 <?xml version="1.0" encoding="UTF-8"?> 445 <svg xmlns="http://www.w3.org/2000/svg" 446 version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400"> 447 <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> 448 <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> 449 </svg> 450
