Currently, LKMM docs are not included in any of kernel documentation
books.
Commit e40573a43d16 ("docs: put atomic*.txt and memory-barriers.txt
into the core-api book") covered plain-text docs under Documentation/
by using the "include::" directive along with the ":literal:" option.
As LKMM docs are not under Documentation/, the same approach would not
work due to the directive's restriction.
As a matter of fact, kernel documentation has an extended directive
by the name of "kernel-include::", which loosens such restriction and
accepts any files under the kernel source tree.
Rather than moving LKMM docs around, use the latter and pull them into
the dev-tools book next to KCSAN.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Paul E. McKenney <paulmck@kernel.org> Acked-by: Paul E. McKenney <paulmck@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <7ce84a93-5cbc-420e-894a-06a0372c52ab@gmail.com>
Jonathan Corbet [Tue, 9 Sep 2025 19:35:37 +0000 (13:35 -0600)]
docs: kdoc: handle the obsolescensce of docutils.ErrorString()
The ErrorString() and SafeString() docutils functions were helpers meant to
ease the handling of encodings during the Python 3 transition. There is no
real need for them after Python 3.6, and docutils 0.22 removes them,
breaking the docs build
Handle this by just injecting our own one-liner version of ErrorString(),
and removing the sole SafeString() call entirely.
Reported-by: Zhixu Liu <zhixu.liu@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <87ldmnv2pi.fsf@trenco.lwn.net>
Jonathan Corbet [Mon, 8 Sep 2025 19:32:10 +0000 (13:32 -0600)]
docs: update the guidance for Link: tags
As stated definitively by Linus, the use of Link: tags should be limited to
situations where there is additional useful information to be found at the
far end of the link. Update our documentation to reflect that policy, and
to remove the suggestion for a Git hook to add those tags automatically.
Documentation: update maintainer-pgp-guide for latest best practices
Freshen up the maintainer PGP guide:
- Bump minimum GnuPG version requirement from 2.2 to 2.4, since 2.2 is
no longer maintained
- All major hardware tokens now support Curve25519, so remove outdated
ECC support callouts
- Update hardware device recommendations (Nitrokey Pro 2 -> Nitrokey 3)
- Broaden backup media terminology (USB thumb drive -> external media)
- Update wording to follow vale's linter recommendations
- Various minor wording improvements for clarity
Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org> Reviewed-by: Paul Barker <paul@pbarker.dev> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250902-pgp-guide-updates-v1-1-62ac7312d3f9@linuxfoundation.org>
Every now and then people send stylistic patches and use Fixes
purely to refer to a commit which added the ugly or unnecessary
code. Reword the docs about Fixes.
It should hopefully be enough to lead with the word "bug"
rather than "issue". We can add more verbiage later, tho, let's
try the word swap first. I always feel like the more words the
smaller the chance someone will actually read the docs.
Signed-off-by: Jakub Kicinski <kuba@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250904144533.2146576-1-kuba@kernel.org>
Jonathan Corbet [Tue, 9 Sep 2025 19:40:35 +0000 (13:40 -0600)]
Merge branch 'renames' into docs-mw
From Vegard Nossum:
When we rename an .rst file, that also changes the URL for the document
at https://docs.kernel.org/ and results in a 404, which can be anonying
for people who bookmark URLs and/or follow links from search engines
and old changelogs and emails.
In order to be able to fearlessly rename individual documentation files
and reorganize Documentation/, add two scripts:
- tools/docs/gen-renames.py : use git to figure out which .rst files
have been renamed
- tools/docs/gen-redirects.py : actually generate .html stubs for the
locations, redirecting to the new locations
The reason for splitting this into two is that trawling git history is
slightly slow (on the order of 20-30 seconds on my laptop) whereas just
generating the HTML files is very fast. This also allows us to cache
the historical renames in Documentation/.renames.txt or add manual
fixups as needed.
Documentation: w1: Fix SPDX comment syntax on masters and slaves toctree index
Commit e9bb627561535d ("docs: w1: convert to ReST and add to the kAPI
group of docs") converts 1-Wire docs to reST alongside with SPDX
comment, yet the comment is written in one dot as opposed to two in
order to be recognized as comment directive, which spills it into
htmldocs output. This issue is partially fixed in d8fb03e1ea64e7 ("docs:
w1: Fix SPDX-License-Identifier syntax") as it only touches top-level w1
toctree.
Do the same fix on masters and slaves toctrees.
Fixes: e9bb62756153 ("docs: w1: convert to ReST and add to the kAPI group of docs") Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250909022142.18007-1-bagasdotme@gmail.com>
Vegard Nossum [Sat, 30 Aug 2025 17:08:08 +0000 (19:08 +0200)]
docs: sphinx: remove SPDX/copyright comments from HTML output
Use Jinja2 comments instead of HTML comments for the SPDX and copyright
lines. This prevents them from appearing in the HTML output, which was
never the intention; the HTML output has its own copyright line at the
bottom of the document.
docs: kernel_include.py: fix an issue when O= is used
As reported by Stephen, building docs with O= is now
broken. Fix it by ensuring that it will seek files under
Kernel source tree.
The original logic was defined to accept including files
under Documentation/output. The new logic doesn't need it
anymore for media, but it might still be useful to preserve
the previous behavior. So, I ended preserving it.
The rule as-is is wrong, as it was inverted. Besides that, after
retest building all repos with suggested LaTeX packages given
by sphinx-pre-install, I was unable to reproduce the issues
I saw with xindy in the past.
So, let's just drop. If anyone reports issues with xindy, we
may need to readd, but at the right way, e.g. {options}{pkgname}.
Bagas Sanjaya [Tue, 19 Aug 2025 06:12:52 +0000 (13:12 +0700)]
Documentation: sharedsubtree: Align text
The docs make heavy use of lists. As it is currently written, these
generate a lot of unnecessary hanging indents since these are not
semantically meant to be definition lists by accident.
Bagas Sanjaya [Tue, 19 Aug 2025 06:12:50 +0000 (13:12 +0700)]
Documentation: sharedsubtree: Use proper enumerator sequence for enumerated lists
Sphinx does not recognize mixed-letter sequences (e.g. 2a) as enumerator
for enumerated lists. As such, lists that use such sequences end up as
definition lists instead.
Use proper enumeration sequences for this purpose.
Fix minor spelling and grammatical issues in the ext4 atomic_writes
documentation.
Signed-off-by: Mallikarjun Thammanavar <mallikarjunst09@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Reviewed-by: Darrick J. Wong <djwong@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250819124604.8995-1-mallikarjunst09@gmail.com
Jonathan Corbet [Fri, 29 Aug 2025 21:58:48 +0000 (15:58 -0600)]
Merge branch 'mauro' into docs-mw
Another build series from Mauro:
The goal of this series is to drop one of the most ancient and ugliest
hack from the documentation build system. Before migrating to Sphinx,
the media subsystem already had a very comprehensive uAPI book, together
with a build time system to detect and point for any documentation gaps.
When migrating to Sphinx, we ported the logic to a Perl script
(parse-headers.pl) and Markus came up with a Sphinx extension
(kernel_include.py). We also added some files to control how parse-headers
produce results, and a Makefile.
At the initial Sphinx versions (1.4.1 if I recall correctly), when
a new symbol is added to videodev2.h, a new warning were
produced at documentatiion time, it the patchset didn't have
the corresponding documentation path.
While kernel-include is generic, the only user at the moment is the media
subsystem.
This series gets rid of the Python script, replacing it by a command
line script and a class. The parse header class can optionally be used by
kernel-include to produce an enriched code that will contain cross-references.
As the other conversions, it starts with a bug-compatible version of
parse-headers, but the subsequent patches add more functionalities and
fix bugs.
It should be noticed that modern of Sphinx disabled the cross-reference
warnings. So, at the next series, I'll be re-adding it in a controlled way
(e.g. just for the references from kernel-include that has an special
argument).
The script also supports now generating a "toc" output, which will be used
at the next series.
scripts: sphinx-build-wrapper: get rid of uapi/media Makefile
Now that kernel-include directive supports parsing data
structs directly, we can finally get rid of the horrible hack
we added to support parsing media uAPI symbols.
As a side effect, Documentation/output doesn't have anymore
media auto-generated .rst files on it.
docs: kernel_include.py: remove Include class inheritance
While the original code came from the Sphinx Include class,
such class is monolithic: it has only one function that does
everything, and 3 variables that are used:
So, basically those are the only members that remain from
the original class, but hey! Those are the same vars that every
other Sphinx directive extension has to define!
In summary, keeping inheritance here doesn't make much sense.
Worse than that, kernel-include doesn't support the current set
of options that the original Include class has, but it also
has its own set of options.
So, let's fill in the argument vars with what it does
support, dropping the rest.
docs: kernel_include.py: remove line numbers from parsed-literal
When parsed-literal directive is added to rawtext, while cross
references will be properly displayed, Sphinx will ignore
line numbers. So, it is not worth adding them.
docs: kernel_include.py: append line numbers to better report errors
It is best to point to the original line of code that generated
an error than to point to the beginning of a directive.
Add support for it. It should be noticed that this won't work
for literal or code blocks, as Sphinx will ignore it, pointing
to the beginning of the directive. Yet, when the output is known
to be in ReST format, like on TOC, this makes the error a lot
more easier to be handled.
docs: kernel_include.py: generate warnings for broken refs
In the past, Sphinx used to warn about broken references. That's
basically the rationale for adding media uAPI files: to get
warnings about missed symbols.
This is not true anymore. So, we need to explicitly check them
after doctree-resolved event.
While here, move setup() to the end, to make it closer to
what we do on other extensions.
kernel_include extension was originally designed to be used by the
media comprehensive uAPI documentation, where, instead of simpler
kernel-doc markups, the uAPI documentation is enriched with a larger
text, with images, complex tables, graphs, etc.
There, we wanted to include the much simpler yet documented .h
file.
This extension is needed to include files from other parts of the
Kernel tree outside Documentation, because the original Sphinx
include tag doesn't allow going outside of the directory passed
via sphinx-build command line.
Yet, the cross-references themselves to the full documentation
were using a perl script to create cross-references against the
comprehensive documentation.
As the perl script is now converted to Phython and there is a
Python class producing an include-compatible output with cross
references, add two optional arguments to kernel_include.py:
1. :generate-cross-refs:
If present, instead of reading the file, it calls ParseDataStructs()
class, which converts C data structures into cross-references to
be linked to ReST files containing a more comprehensive documentation;
Don't use it together with :start-line: and/or :end-line:, as
filtering input file line range is currently not supported.
2. :exception-file:
Used together with :generate-cross-refs:. Points to a file containing
rules to ignore C data structs or to use a different reference name,
optionally using a different reference type.
tools: docs: parse_data_structs.py: add methods to return output
When running it from command line, we want to write an output
file, but when used as a class, one may just want the output
content returned as a string.
Split write_output() on two methods to allow both usecases.
docs: parse-headers.py: simplify the rules for hashes
Normal :ref domain accept either hashes or underscores, but
c-domain ones don't. Fix it and remove unneeded places where
we opt to disable underscore transformation.
Ideally, we should have a rule about the default, or change
the way media docs have their references.
When printing --help, we'd like the name of the files
from __doc__ to match the displayed positional arguments at
both usage and argument description lines.
Use a custom formatter class to convert ``foo`` into ANSI SGR
code to bold the argument, if is TTY, and adjust the help
text to match the argument names.
Here on Plasma, that makes it display it colored, wich is
really cool. Yet, I opted for SGR, as the best is to follow
the terminal color schema for bold.
When the Kernel started to use Sphinx, we had to come up with
a solution to parse media headers. On that time, we didn't have
much experience with Sphinx extensions. So, we came up with our
own script-based solution that were basically implementing a
set of rules we used to have at the Makefile.
Convert it to Python, keeping it bug-compatible with the
original script.
Bagas Sanjaya [Tue, 26 Aug 2025 02:47:56 +0000 (09:47 +0700)]
Documentation: ocfs2: Properly reindent filecheck operations list
Some of texts in filecheck operations list are indented out of the list.
In particular, the third operation is shown not as the third list
item but rather as a separate paragraph.
Reindent the list so that gets properly rendered as such.
Alex Tran [Wed, 27 Aug 2025 07:45:25 +0000 (00:45 -0700)]
docs: driver-api pinctrl cleanup
Replace FIXME comments in the pinctrl documentation example with
proper cleanup code:
- Add devm_pinctrl_put() calls in error paths
(pinctrl_lookup_state, pinctrl_select_state)
after successful devm_pinctrl_get()
- Set foo->p to NULL when devm_pinctrl_get() fails
- Add ret variable for cleaner error handling
- provides proper example of pinctrl resource management on failure
Jonathan Corbet [Thu, 21 Aug 2025 20:09:21 +0000 (14:09 -0600)]
Merge branch 'mauro-pdf' into docs-mw
Here it is the second version of the PDF series. I opted to split one of
the patches in 3, to have a clearer changelog and description.
Also, archlinux LXC image download started working again, so I added
an extra patch addressing texlive packae dependencies.
This series is taking me a way more time than antecipated.
This series as 3 goals:
1. Fix a pre-Sphinx 1.7 PDF variable that got renamed, but
our Makefile still uses the old one that is not supported
since Sphinx 1.7;
2. Fix broken or incomplete texlive dependencies on several
distros;
4. "modernize" conf.py to solve font conflicts related to UTF-8
and non-UTF fonts from [T1]{fontenc} LaTeX package.
Using fontenc with xelatex is problematic, as documented at
https://www.sphinx-doc.org/en/master/latex.html
Please notice that:
- It doesn't pretend to fix all PDF issues. It focus only at the
above;
- there are still distros where PDF builds fail either partially
or as a hole. On my checks, those are due to problematic
texlive packages shipped on such distros;
- it doesn't touch/address/alter anyhing related to kfigure.py.
as such, it doesn't touch/change/improve/drop anything with
regards ImageMagick and/or Inkscape.
scripts/sphinx-pre-install: fix Archlinux PDF dependencies
There are some missing packages causing PDF build to fail on
Archlinux and add latexmk (from texlive-binextra package).
Yet, at least today, PDF builds are failing on a very late
stage, when trying to run xdvipdfmx:
$ xdvipdfmx -E -o "peci.pdf" "peci.xdv"
xdvipdfmx:fatal: Unrecognized paper format: # Simply write the paper name. See man 1 paper and "paper --no-size --all" for possible values
Despite its message, even using a very simple document like:
\def\sphinxdocclass{report}
\documentclass[a4paper,11pt,english]{sphinxmanual}
\begin{document}
Test
\end{document}
or even:
\def\sphinxdocclass{report}
\documentclass{sphinxmanual}
\begin{document}
Test
\end{document}
Is causing xdvipdfmx to complain about geometry. As Archlinux is
a rolling release distro, maybe I got it on a bad day. So, let's
fix it in the hope that soon enough someone would fix the issues
there.
Such broken scenario happens with those packages installed:
scripts: sphinx-pre-install: add missing gentoo pdf dependencies
There are two packages that are required to build PDF at gentoo:
dev-texlive/texlive-latexextra
media-fonts/lm
Place latex_dependencies on a list to make it easier to maintain
and add the missing ones.
With that, most PDF documents now build on Gentoo:
Gentoo Base System release 2.17:
--------------------------------
PASSED: OS detection: Gentoo Base System release 2.17
SKIPPED (Sphinx Sphinx 8.2.3): System packages
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx on venv
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx package
PASSED: Clean documentation: Build time: 0:00, return code: 0
PASSED: Build HTML documentation: Build time: 5:28, return code: 0
PARTIAL: Build PDF documentation: Test failed (Build time: 9:19, return code: 2)
scripts: sphinx-pre-install: fix PDF build issues on Ubuntu
PDF output with current Debian-based distros require other
packages for it to work. The main one is pzdr.tfm. Without
that, \sphinxhyphen{} won't work, affecting multiple docs.
For CJK, tex-gyre is required.
Add the missing packages to the list.
After the change, all PDF files build on latest Ubuntu:
Ubuntu 25.04:
-------------
PASSED: OS detection: Ubuntu 25.04
SKIPPED (Sphinx Sphinx 8.1.3): System packages
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx on venv
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx package
PASSED: Clean documentation: Build time: 0:00, return code: 0
PASSED: Build HTML documentation: Build time: 3:28, return code: 0
PASSED: Build PDF documentation: Build time: 11:08, return code: 0
Makes it more adehent with modern Sphinx LaTeX build setup as
defined at:
https://www.sphinx-doc.org/en/master/latex.html
There, it suggests:
1) to add: 'printindex'
“printindex” call, the last thing in the file. Override if you want to generate
the index differently, append some content after the index, or change the font.
As LaTeX uses two-column mode for the index it is often advisable to set this
key to r'\footnotesize\raggedright\printindex'.
This indeed solved a corner case on a distro where the index was not properly
generated.
2) to add at the main example:
\PassOptionsToPackage{svgnames}{xcolor}
3) I got a corner case on one of the distros was using xindy to produce
indexes. This ended causing the build logic to incorretly try to use
T1 fontenc, which is not UTF-8 compatible.
While PDF docs work fine on RPM-based distros, it causes conflicts
on Debian & friends.
There are multiple root causes here:
- the latex_elements still resambles the one from Sphinx 1.x
times, where font configurations were stored under
"preamble". It doesn't follow the current recommended way from
Sphinx documentation:
https://www.sphinx-doc.org/en/master/latex.html
- instead of setting the main font, from where other fonts are
derivated, it sets romanfont;
- "fontenc" is not set. This allows the *.tex output file to
contain an UTF-8 incompatible fontset:
\usepackage[T1]{fontenc}
Address such issues to help preventing incompatible usage of
both T1 font and UTF-8 ones that comes from DejaVu font
family.
On some distros, this even generate a LaTeX font warning about
corrupted NFSS tables like this (I got it when running it in
interactive mode):
Package: fontenc 2021/04/29 v2.0v Standard LaTeX package
LaTeX Font Info: Trying to load font information for T1+lmr on input line 11
6.
LaTeX Font Info: No file T1lmr.fd. on input line 116.
LaTeX Font Warning: Font shape `T1/lmr/m/n' undefined
(Font) using `T1/lmr/m/n' instead on input line 116.
docs: conf.py: use dedent and r-strings for LaTeX macros
Instead of adding extra weird indentation at the tex
file, use dedent(). While here, also use r-strings, to make
easier to make its content identical to the .tex output.
While here, also merge "preamble" that was added on two
separate parts of the code (in the past, there were some
version-specific checks).
When SPHINXDIRS is used, the current logic produces a wrong
list of files, as it will not pick the SPHINXDIRS directory,
picking instead their children.
Add a rule to detect it and create the PDF doc with the right
name.
The original logic assumed that app.srcdir is identical to the
current working dir. This is the case for a normal build, but,
when SPHINXDIRS="some dir" is used, this is not the case anymore.
Adjust the logic to fill the LaTeX documents considering
app.srcdir, in a way that it will work properly on all cases.
The documents explain the design concepts behind PREEMPT_RT and highlight key
differences necessary to achieve it.
It also include a list of requirements that must be fulfilled to support
PREEMPT_RT on a given architecture.
docs: fix trailing whitespace error and remove repeated words in propagate_umount.txt
in Documentation/filesystems/propagate_umount.txt:
line 289: remove whitespace on blank line
line 315: remove duplicate "that"
line 364: remove duplicate "in"
toctree index in USB driver api docs currently spoils the entire docs
headings due to lack of :maxdepth: option. Add the option to limit
toctree depth to 1, mirroring usb subsystem docs in
Documentation/usb/index.rst.
David Sterba [Wed, 13 Aug 2025 10:00:52 +0000 (12:00 +0200)]
docs: Remove remainders of reiserfs
Reiserfs has been removed in 6.13, there are still some mentions in the
documentation about it and the tools. Remove those that don't seem
relevant anymore but keep references to reiserfs' r5 hash used by some
code.
There's one change in a script scripts/selinux/install_policy.sh but it
does not seem to be relevant either.
Jonathan Corbet [Thu, 14 Aug 2025 15:40:33 +0000 (09:40 -0600)]
docs: kdoc: tighten up the array-of-pointers case
Simplify one gnarly regex and remove another altogether; add a comment
describing what is going on. There will be no #-substituted commas in this
case, so don't bother trying to put them back.
Jonathan Corbet [Thu, 14 Aug 2025 15:40:31 +0000 (09:40 -0600)]
docs: kdoc: clean up the create_parameter_list() "first arg" logic
The logic for finding the name of the first in a series of variable names
is somewhat convoluted and, in the use of .extend(), actively buggy.
Document what is happening and simplify the logic.
Jonathan Corbet [Thu, 14 Aug 2025 15:40:29 +0000 (09:40 -0600)]
docs: kdoc: remove dead code
create_parameter_list() tests an argument against the same regex twice, in
two different locations; remove the pointless extra tests and the
never-executed error cases that go with them.
projects / thirdparty / kernel / stable.git / log
