Documentation/doc-guide/sphinx.rst

4 Using Sphinx for kernel documentation
7 The Linux kernel uses `Sphinx`_ to generate pretty documentation from
8 `reStructuredText`_ files under ``Documentation``. To build the documentation in
10 documentation is placed in ``Documentation/output``.
16 documentation comments, or kernel-doc comments, from source files. Usually these
21 Finally, there are thousands of plain text documentation files scattered around
22 ``Documentation``. Some of these will likely be converted to reStructuredText
30 The ReST markups currently used by the Documentation/ files are meant to be
38 on your machine would cause the documentation build to break.
55        (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
60 the virtual environment before building the documentation.
65 The kernel documentation build system contains an extension that
71 still build the documentation, but won't include any images at the
95 The former was the only option for pre-6.1 kernel documentation and it
123 		pip install -r Documentation/sphinx/requirements.txt
144 The usual way to generate the documentation is to run ``make htmldocs`` or
145 ``make pdfdocs``. There are also other formats available: see the documentation
146 section of ``make help``. The generated documentation is placed in
147 format-specific subdirectories under ``Documentation/output``.
149 To generate documentation, Sphinx (``sphinx-build``) must obviously be
161 By default, the "Alabaster" theme is used to build the HTML documentation;
166 building a subset of documentation.  For example, you can build documents
167 under ``Documentation/doc-guide`` by running
169 The documentation section of ``make help`` will show you the list of
172 To remove the generated documentation, run ``make cleandocs``.
210 Writing Documentation
213 Adding new documentation can be as simple as:
215 1. Add a new ``.rst`` file somewhere under ``Documentation``.
216 2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
220 This is usually good enough for simple documentation (like the one you're
223 documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
227 See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
235 Specific guidelines for the kernel documentation
238 Here are some specific guidelines for the kernel documentation:
241   simple. For the most part the documentation should be plain text with
246   documentation to reStructuredText.
249   documentation.
289 The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a
310 references to function documentation.  Due to some Sphinx extension magic,
311 the documentation build system will automatically turn a reference to
414 Cross-referencing from one documentation page to another can be done simply by
417 "Documentation/". For example, to cross-reference to this page, all the
421     See Documentation/doc-guide/sphinx.rst. This always works.
436 Documentation/doc-guide/kernel-doc.rst.