540 lines · plain
1.. _sphinxdoc:2 3=====================================4Using Sphinx for kernel documentation5=====================================6 7The Linux kernel uses `Sphinx`_ to generate pretty documentation from8`reStructuredText`_ files under ``Documentation``. To build the documentation in9HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated10documentation is placed in ``Documentation/output``.11 12.. _Sphinx: http://www.sphinx-doc.org/13.. _reStructuredText: http://docutils.sourceforge.net/rst.html14 15The reStructuredText files may contain directives to include structured16documentation comments, or kernel-doc comments, from source files. Usually these17are used to describe the functions and types and design of the code. The18kernel-doc comments have some special structure and formatting, but beyond that19they are also treated as reStructuredText.20 21Finally, there are thousands of plain text documentation files scattered around22``Documentation``. Some of these will likely be converted to reStructuredText23over time, but the bulk of them will remain in plain text.24 25.. _sphinx_install:26 27Sphinx Install28==============29 30The ReST markups currently used by the Documentation/ files are meant to be31built with ``Sphinx`` version 2.4.4 or higher.32 33There's a script that checks for the Sphinx requirements. Please see34:ref:`sphinx-pre-install` for further details.35 36Most distributions are shipped with Sphinx, but its toolchain is fragile,37and it is not uncommon that upgrading it or some other Python packages38on your machine would cause the documentation build to break.39 40A way to avoid that is to use a different version than the one shipped41with your distributions. In order to do so, it is recommended to install42Sphinx inside a virtual environment, using ``virtualenv-3``43or ``virtualenv``, depending on how your distribution packaged Python 3.44 45.. note::46 47 #) It is recommended to use the RTD theme for html output. Depending48 on the Sphinx version, it should be installed separately,49 with ``pip install sphinx_rtd_theme``.50 51In summary, if you want to install the latest version of Sphinx, you52should do::53 54 $ virtualenv sphinx_latest55 $ . sphinx_latest/bin/activate56 (sphinx_latest) $ pip install -r Documentation/sphinx/requirements.txt57 58After running ``. sphinx_latest/bin/activate``, the prompt will change,59in order to indicate that you're using the new environment. If you60open a new shell, you need to rerun this command to enter again at61the virtual environment before building the documentation.62 63Image output64------------65 66The kernel documentation build system contains an extension that67handles images in both GraphViz and SVG formats (see :ref:`sphinx_kfigure`).68 69For it to work, you need to install both GraphViz and ImageMagick70packages. If those packages are not installed, the build system will71still build the documentation, but won't include any images at the72output.73 74PDF and LaTeX builds75--------------------76 77Such builds are currently supported only with Sphinx versions 2.4 and higher.78 79For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265.80 81Depending on the distribution, you may also need to install a series of82``texlive`` packages that provide the minimal set of functionalities83required for ``XeLaTeX`` to work.84 85Math Expressions in HTML86------------------------87 88Some ReST pages contain math expressions. Due to the way Sphinx works,89those expressions are written using LaTeX notation.90There are two options for Sphinx to render math expressions in html output.91One is an extension called `imgmath`_ which converts math expressions into92images and embeds them in html pages.93The other is an extension called `mathjax`_ which delegates math rendering94to JavaScript capable web browsers.95The former was the only option for pre-6.1 kernel documentation and it96requires quite a few texlive packages including amsfonts and amsmath among97others.98 99Since kernel release 6.1, html pages with math expressions can be built100without installing any texlive packages. See `Choice of Math Renderer`_ for101further info.102 103.. _imgmath: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.imgmath104.. _mathjax: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax105 106.. _sphinx-pre-install:107 108Checking for Sphinx dependencies109--------------------------------110 111There's a script that automatically checks for Sphinx dependencies. If it can112recognize your distribution, it will also give a hint about the install113command line options for your distro::114 115 $ ./scripts/sphinx-pre-install116 Checking if the needed tools for Fedora release 26 (Twenty Six) are available117 Warning: better to also install "texlive-luatex85".118 You should run:119 120 sudo dnf install -y texlive-luatex85121 /usr/bin/virtualenv sphinx_2.4.4122 . sphinx_2.4.4/bin/activate123 pip install -r Documentation/sphinx/requirements.txt124 125 Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.126 127By default, it checks all the requirements for both html and PDF, including128the requirements for images, math expressions and LaTeX build, and assumes129that a virtual Python environment will be used. The ones needed for html130builds are assumed to be mandatory; the others to be optional.131 132It supports two optional parameters:133 134``--no-pdf``135 Disable checks for PDF;136 137``--no-virtualenv``138 Use OS packaging for Sphinx instead of Python virtual environment.139 140 141Sphinx Build142============143 144The usual way to generate the documentation is to run ``make htmldocs`` or145``make pdfdocs``. There are also other formats available: see the documentation146section of ``make help``. The generated documentation is placed in147format-specific subdirectories under ``Documentation/output``.148 149To generate documentation, Sphinx (``sphinx-build``) must obviously be150installed. For PDF output you'll also need ``XeLaTeX`` and ``convert(1)``151from ImageMagick (https://www.imagemagick.org).\ [#ink]_ All of these are152widely available and packaged in distributions.153 154To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make155variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose156output.157 158It is also possible to pass an extra DOCS_CSS overlay file, in order to customize159the html layout, by using the ``DOCS_CSS`` make variable.160 161By default, the "Alabaster" theme is used to build the HTML documentation;162this theme is bundled with Sphinx and need not be installed separately.163The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.164 165There is another make variable ``SPHINXDIRS``, which is useful when test166building a subset of documentation. For example, you can build documents167under ``Documentation/doc-guide`` by running168``make SPHINXDIRS=doc-guide htmldocs``.169The documentation section of ``make help`` will show you the list of170subdirectories you can specify.171 172To remove the generated documentation, run ``make cleandocs``.173 174.. [#ink] Having ``inkscape(1)`` from Inkscape (https://inkscape.org)175 as well would improve the quality of images embedded in PDF176 documents, especially for kernel releases 5.18 and later.177 178Choice of Math Renderer179-----------------------180 181Since kernel release 6.1, mathjax works as a fallback math renderer for182html output.\ [#sph1_8]_183 184Math renderer is chosen depending on available commands as shown below:185 186.. table:: Math Renderer Choices for HTML187 188 ============= ================= ============189 Math renderer Required commands Image format190 ============= ================= ============191 imgmath latex, dvipng PNG (raster)192 mathjax193 ============= ================= ============194 195The choice can be overridden by setting an environment variable196``SPHINX_IMGMATH`` as shown below:197 198.. table:: Effect of Setting ``SPHINX_IMGMATH``199 200 ====================== ========201 Setting Renderer202 ====================== ========203 ``SPHINX_IMGMATH=yes`` imgmath204 ``SPHINX_IMGMATH=no`` mathjax205 ====================== ========206 207.. [#sph1_8] Fallback of math renderer requires Sphinx >=1.8.208 209 210Writing Documentation211=====================212 213Adding new documentation can be as simple as:214 2151. Add a new ``.rst`` file somewhere under ``Documentation``.2162. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.217 218.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html219 220This is usually good enough for simple documentation (like the one you're221reading right now), but for larger documents it may be advisable to create a222subdirectory (or use an existing one). For example, the graphics subsystem223documentation is under ``Documentation/gpu``, split to several ``.rst`` files,224and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from225the main index.226 227See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do228with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place229to get started with reStructuredText. There are also some `Sphinx specific230markup constructs`_.231 232.. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html233.. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html234 235Specific guidelines for the kernel documentation236------------------------------------------------237 238Here are some specific guidelines for the kernel documentation:239 240* Please don't go overboard with reStructuredText markup. Keep it241 simple. For the most part the documentation should be plain text with242 just enough consistency in formatting that it can be converted to243 other formats.244 245* Please keep the formatting changes minimal when converting existing246 documentation to reStructuredText.247 248* Also update the content, not just the formatting, when converting249 documentation.250 251* Please stick to this order of heading adornments:252 253 1. ``=`` with overline for document title::254 255 ==============256 Document title257 ==============258 259 2. ``=`` for chapters::260 261 Chapters262 ========263 264 3. ``-`` for sections::265 266 Section267 -------268 269 4. ``~`` for subsections::270 271 Subsection272 ~~~~~~~~~~273 274 Although RST doesn't mandate a specific order ("Rather than imposing a fixed275 number and order of section title adornment styles, the order enforced will be276 the order as encountered."), having the higher levels the same overall makes277 it easier to follow the documents.278 279* For inserting fixed width text blocks (for code examples, use case280 examples, etc.), use ``::`` for anything that doesn't really benefit281 from syntax highlighting, especially short snippets. Use282 ``.. code-block:: <language>`` for longer code blocks that benefit283 from highlighting. For a short snippet of code embedded in the text, use \`\`.284 285 286The C domain287------------288 289The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a290function prototype:291 292.. code-block:: rst293 294 .. c:function:: int ioctl( int fd, int request )295 296The C domain of the kernel-doc has some additional features. E.g. you can297*rename* the reference name of a function with a common name like ``open`` or298``ioctl``:299 300.. code-block:: rst301 302 .. c:function:: int ioctl( int fd, int request )303 :name: VIDIOC_LOG_STATUS304 305The func-name (e.g. ioctl) remains in the output but the ref-name changed from306``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also307changed to ``VIDIOC_LOG_STATUS``.308 309Please note that there is no need to use ``c:func:`` to generate cross310references to function documentation. Due to some Sphinx extension magic,311the documentation build system will automatically turn a reference to312``function()`` into a cross reference if an index entry for the given313function name exists. If you see ``c:func:`` use in a kernel document,314please feel free to remove it.315 316Tables317------318 319ReStructuredText provides several options for table syntax. Kernel style for320tables is to prefer *simple table* syntax or *grid table* syntax. See the321`reStructuredText user reference for table syntax`_ for more details.322 323.. _reStructuredText user reference for table syntax:324 https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables325 326list tables327~~~~~~~~~~~328 329The list-table formats can be useful for tables that are not easily laid330out in the usual Sphinx ASCII-art formats. These formats are nearly331impossible for readers of the plain-text documents to understand, though,332and should be avoided in the absence of a strong justification for their333use.334 335The ``flat-table`` is a double-stage list similar to the ``list-table`` with336some additional features:337 338* column-span: with the role ``cspan`` a cell can be extended through339 additional columns340 341* row-span: with the role ``rspan`` a cell can be extended through342 additional rows343 344* auto span rightmost cell of a table row over the missing cells on the right345 side of that table-row. With Option ``:fill-cells:`` this behavior can346 changed from *auto span* to *auto fill*, which automatically inserts (empty)347 cells instead of spanning the last cell.348 349options:350 351* ``:header-rows:`` [int] count of header rows352* ``:stub-columns:`` [int] count of stub columns353* ``:widths:`` [[int] [int] ... ] widths of columns354* ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells355 356roles:357 358* ``:cspan:`` [int] additional columns (*morecols*)359* ``:rspan:`` [int] additional rows (*morerows*)360 361The example below shows how to use this markup. The first level of the staged362list is the *table-row*. In the *table-row* there is only one markup allowed,363the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )364and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row365<last row>`).366 367.. code-block:: rst368 369 .. flat-table:: table title370 :widths: 2 1 1 3371 372 * - head col 1373 - head col 2374 - head col 3375 - head col 4376 377 * - row 1378 - field 1.1379 - field 1.2 with autospan380 381 * - row 2382 - field 2.1383 - :rspan:`1` :cspan:`1` field 2.2 - 3.3384 385 * .. _`last row`:386 387 - row 3388 389Rendered as:390 391 .. flat-table:: table title392 :widths: 2 1 1 3393 394 * - head col 1395 - head col 2396 - head col 3397 - head col 4398 399 * - row 1400 - field 1.1401 - field 1.2 with autospan402 403 * - row 2404 - field 2.1405 - :rspan:`1` :cspan:`1` field 2.2 - 3.3406 407 * .. _`last row`:408 409 - row 3410 411Cross-referencing412-----------------413 414Cross-referencing from one documentation page to another can be done simply by415writing the path to the document file, no special syntax required. The path can416be either absolute or relative. For absolute paths, start it with417"Documentation/". For example, to cross-reference to this page, all the418following are valid options, depending on the current document's directory (note419that the ``.rst`` extension is required)::420 421 See Documentation/doc-guide/sphinx.rst. This always works.422 Take a look at sphinx.rst, which is at this same directory.423 Read ../sphinx.rst, which is one directory above.424 425If you want the link to have a different rendered text other than the document's426title, you need to use Sphinx's ``doc`` role. For example::427 428 See :doc:`my custom link text for document sphinx <sphinx>`.429 430For most use cases, the former is preferred, as it is cleaner and more suited431for people reading the source files. If you come across a ``:doc:`` usage that432isn't adding any value, please feel free to convert it to just the document433path.434 435For information on cross-referencing to kernel-doc functions or types, see436Documentation/doc-guide/kernel-doc.rst.437 438Referencing commits439~~~~~~~~~~~~~~~~~~~440 441References to git commits are automatically hyperlinked given that they are442written in one of these formats::443 444 commit 72bf4f1767f0445 commit 72bf4f1767f0 ("net: do not leave an empty skb in write queue")446 447.. _sphinx_kfigure:448 449Figures & Images450================451 452If you want to add an image, you should use the ``kernel-figure`` and453``kernel-image`` directives. E.g. to insert a figure with a scalable454image format, use SVG (:ref:`svg_image_example`)::455 456 .. kernel-figure:: svg_image.svg457 :alt: simple SVG image458 459 SVG image example460 461.. _svg_image_example:462 463.. kernel-figure:: svg_image.svg464 :alt: simple SVG image465 466 SVG image example467 468The kernel figure (and image) directive supports **DOT** formatted files, see469 470* DOT: http://graphviz.org/pdf/dotguide.pdf471* Graphviz: http://www.graphviz.org/content/dot-language472 473A simple example (:ref:`hello_dot_file`)::474 475 .. kernel-figure:: hello.dot476 :alt: hello world477 478 DOT's hello world example479 480.. _hello_dot_file:481 482.. kernel-figure:: hello.dot483 :alt: hello world484 485 DOT's hello world example486 487Embedded *render* markups (or languages) like Graphviz's **DOT** are provided by the488``kernel-render`` directives.::489 490 .. kernel-render:: DOT491 :alt: foobar digraph492 :caption: Embedded **DOT** (Graphviz) code493 494 digraph foo {495 "bar" -> "baz";496 }497 498How this will be rendered depends on the installed tools. If Graphviz is499installed, you will see a vector image. If not, the raw markup is inserted as500*literal-block* (:ref:`hello_dot_render`).501 502.. _hello_dot_render:503 504.. kernel-render:: DOT505 :alt: foobar digraph506 :caption: Embedded **DOT** (Graphviz) code507 508 digraph foo {509 "bar" -> "baz";510 }511 512The *render* directive has all the options known from the *figure* directive,513plus option ``caption``. If ``caption`` has a value, a *figure* node is514inserted. If not, an *image* node is inserted. A ``caption`` is also needed, if515you want to refer to it (:ref:`hello_svg_render`).516 517Embedded **SVG**::518 519 .. kernel-render:: SVG520 :caption: Embedded **SVG** markup521 :alt: so-nw-arrow522 523 <?xml version="1.0" encoding="UTF-8"?>524 <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>525 ...526 </svg>527 528.. _hello_svg_render:529 530.. kernel-render:: SVG531 :caption: Embedded **SVG** markup532 :alt: so-nw-arrow533 534 <?xml version="1.0" encoding="UTF-8"?>535 <svg xmlns="http://www.w3.org/2000/svg"536 version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">537 <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>538 <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>539 </svg>540