Image output¶

The kernel documentation build system contains an extension thathandles images in both GraphViz and SVG formats (seeFigures & Images).

For it to work, you need to install both GraphViz and ImageMagickpackages. If those packages are not installed, the build system willstill build the documentation, but won’t include any images at theoutput.

PDF and LaTeX builds¶

Such builds are currently supported only with Sphinx versions 2.4 and higher.

For PDF and LaTeX output, you’ll also needXeLaTeX version 3.14159265.

Depending on the distribution, you may also need to install a series oftexlive packages that provide the minimal set of functionalitiesrequired forXeLaTeX to work.

Math Expressions in HTML¶

Some ReST pages contain math expressions. Due to the way Sphinx works,those expressions are written using LaTeX notation.There are two options for Sphinx to render math expressions in html output.One is an extension calledimgmath which converts math expressions intoimages and embeds them in html pages.The other is an extension calledmathjax which delegates math renderingto JavaScript capable web browsers.The former was the only option for pre-6.1 kernel documentation and itrequires quite a few texlive packages including amsfonts and amsmath amongothers.

Since kernel release 6.1, html pages with math expressions can be builtwithout installing any texlive packages. SeeChoice of Math Renderer forfurther info.

Checking for Sphinx dependencies¶

There’s a script that automatically checks for Sphinx dependencies. If it canrecognize your distribution, it will also give a hint about the installcommand line options for your distro:

$ ./tools/docs/sphinx-pre-installChecking if the needed tools for Fedora release 26 (Twenty Six) are availableWarning: better to also install "texlive-luatex85".You should run:        sudo dnf install -y texlive-luatex85        /usr/bin/virtualenv sphinx_2.4.4        . sphinx_2.4.4/bin/activate        pip install -r Documentation/sphinx/requirements.txtCan't build as 1 mandatory dependency is missing at ./tools/docs/sphinx-pre-install line 468.

By default, it checks all the requirements for both html and PDF, includingthe requirements for images, math expressions and LaTeX build, and assumesthat a virtual Python environment will be used. The ones needed for htmlbuilds are assumed to be mandatory; the others to be optional.

It supports two optional parameters:

--no-pdf

Disable checks for PDF;

--no-virtualenv

Use OS packaging for Sphinx instead of Python virtual environment.

Installing Sphinx Minimal Version¶

When changing Sphinx build system, it is important to ensure thatthe minimal version will still be supported. Nowadays, it isbecoming harder to do that on modern distributions, as it is notpossible to install with Python 3.13 and above.

Testing with the lowest supported Python version as defined atMinimal requirements to compile the Kernel can be done by creatinga venv with it with, and install minimal requirements with:

/usr/bin/python3.9 -m venv sphinx_min. sphinx_min/bin/activatepip install -r Documentation/sphinx/min_requirements.txt

A more comprehensive test can be done by using:

tools/docs/test_doc_build.py

Such script create one Python venv per supported version,optionally building documentation for a range of Sphinx versions.

Choice of Math Renderer¶

Since kernel release 6.1, mathjax works as a fallback math renderer forhtml output.[2]

Math renderer is chosen depending on available commands as shown below:

The choice can be overridden by setting an environment variableSPHINX_IMGMATH as shown below:

Fallback of math renderer requires Sphinx >=1.8.

Specific guidelines for the kernel documentation¶

Here are some specific guidelines for the kernel documentation:

• Please don’t go overboard with reStructuredText markup. Keep itsimple. For the most part the documentation should be plain text withjust enough consistency in formatting that it can be converted toother formats.

• Please keep the formatting changes minimal when converting existingdocumentation to reStructuredText.

• Also update the content, not just the formatting, when convertingdocumentation.

• Please stick to this order of heading adornments:

  1. = with overline for document title:

     ==============Document title==============

  2. = for chapters:

     Chapters========

  3. - for sections:

     Section-------

  4. ~ for subsections:

     Subsection~~~~~~~~~~

  Although RST doesn’t mandate a specific order (“Rather than imposing a fixednumber and order of section title adornment styles, the order enforced will bethe order as encountered.”), having the higher levels the same overall makesit easier to follow the documents.

• For inserting fixed width text blocks (for code examples, use caseexamples, etc.), use:: for anything that doesn’t really benefitfrom syntax highlighting, especially short snippets. Use..code-block::<language> for longer code blocks that benefitfrom highlighting. For a short snippet of code embedded in the text, use ``.

The C domain¶

TheSphinx C Domain (name c) is suited for documentation of C API. E.g. afunction prototype:

..c:function:: int ioctl( int fd, int request )

The C domain of the kernel-doc has some additional features. E.g. you canrename the reference name of a function with a common name likeopen orioctl:

..c:function:: int ioctl( int fd, int request ):name: VIDIOC_LOG_STATUS

The func-name (e.g. ioctl) remains in the output but the ref-name changed fromioctl toVIDIOC_LOG_STATUS. The index entry for this function is alsochanged toVIDIOC_LOG_STATUS.

Please note that there is no need to usec:func: to generate crossreferences to function documentation. Due to some Sphinx extension magic,the documentation build system will automatically turn a reference tofunction() into a cross reference if an index entry for the givenfunction name exists. If you seec:func: use in a kernel document,please feel free to remove it.

Tables¶

ReStructuredText provides several options for table syntax. Kernel style fortables is to prefersimple table syntax orgrid table syntax. See thereStructuredText user reference for table syntax for more details.

..flat-table:: table title:widths: 2 1 1 3* - head col 1- head col 2- head col 3- head col 4* - row 1- field 1.1- field 1.2 with autospan* - row 2- field 2.1-:rspan:`1`:cspan:`1` field 2.2 - 3.3* .. _`last row`:- row 3

Cross-referencing¶

Cross-referencing from one documentation page to another can be done simply bywriting the path to the document file, no special syntax required. The path canbe either absolute or relative. For absolute paths, start it with“Documentation/”. For example, to cross-reference to this page, all thefollowing are valid options, depending on the current document’s directory (notethat the.rst extension is required):

See Documentation/doc-guide/sphinx.rst. This always works.Take a look at sphinx.rst, which is at this same directory.Read ../sphinx.rst, which is one directory above.

If you want the link to have a different rendered text other than the document’stitle, you need to use Sphinx’sdoc role. For example:

See :doc:`my custom link text for document sphinx <sphinx>`.

For most use cases, the former is preferred, as it is cleaner and more suitedfor people reading the source files. If you come across a:doc: usage thatisn’t adding any value, please feel free to convert it to just the documentpath.

For information on cross-referencing to kernel-doc functions or types, seeWriting kernel-doc comments.

commit 72bf4f1767f0commit 72bf4f1767f0 ("net: do not leave an empty skb in write queue")