sphinx.rst

Introduction

The Linux kernel uses Sphinx to generate pretty documentation from reStructuredText files under Documentation. To build the documentation in HTML or PDF formats, use make htmldocs or make pdfdocs. The generated documentation is placed in Documentation/output.

The reStructuredText files may contain directives to include structured documentation comments, or kernel-doc comments, from source files. Usually these are used to describe the functions and types and design of the code. The kernel-doc comments have some special structure and formatting, but beyond that they are also treated as reStructuredText.

Finally, there are thousands of plain text documentation files scattered around Documentation. Some of these will likely be converted to reStructuredText over time, but the bulk of them will remain in plain text.

Sphinx Install

The ReST markups currently used by the Documentation/ files are meant to be built with Sphinx version 1.3 or upper. If you're desiring to build PDF outputs, it is recommended to use version 1.4.6 or upper.

There's a script that checks for the Sphinx requirements. Please see :ref:`sphinx-pre-install` for further details.

Most distributions are shipped with Sphinx, but its toolchain is fragile, and it is not uncommon that upgrading it or some other Python packages on your machine would cause the documentation build to break.

A way to get rid of that is to use a different version than the one shipped on your distributions. In order to do that, it is recommended to install Sphinx inside a virtual environment, using virtualenv-3 or virtualenv, depending on how your distribution packaged Python 3.

Note

1. Sphinx versions below 1.5 don't work properly with Python's docutils version 0.13.1 or upper. So, if you're willing to use those versions, you should run pip install 'docutils==0.12'.
2. It is recommended to use the RTD theme for html output. Depending on the Sphinx version, it should be installed in separate, with pip install sphinx_rtd_theme.
3. Some ReST pages contain math expressions. Due to the way Sphinx work, those expressions are written using LaTeX notation. It needs texlive installed with amdfonts and amsmath in order to evaluate them.

In summary, if you want to install Sphinx version 1.4.9, you should do:

$ virtualenv sphinx_1.4
$ . sphinx_1.4/bin/activate
(sphinx_1.4) $ pip install -r Documentation/sphinx/requirements.txt

After running . sphinx_1.4/bin/activate, the prompt will change, in order to indicate that you're using the new environment. If you open a new shell, you need to rerun this command to enter again at the virtual environment before building the documentation.

Image output

The kernel documentation build system contains an extension that handles images on both GraphViz and SVG formats (see :ref:`sphinx_kfigure`).

For it to work, you need to install both GraphViz and ImageMagick packages. If those packages are not installed, the build system will still build the documentation, but won't include any images at the output.