This is not used anymore, as it was a logic we had to support
pre Sphinx 3.x, as shown at:
afde706afd ("Make the docs build "work" with Sphinx 3.x")
Remove it.
Fixes: b26717852d ("docs: conf.py: drop backward support for old Sphinx versions")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <3b86d236c64af17924e4cfedbbfb8bc60059802f.1758381727.git.mchehab+huawei@kernel.org>
Commit 1e9ddbb2cd ("docs: Pull LKMM documentation into dev-tools book")
failed to add a file extension in lkmm/docs/herd-representation.rst for
referencing its plane-text counterpart.
Fix it.
Fixes: 1e9ddbb2cd ("docs: Pull LKMM documentation into dev-tools book")
Reported-by: kernel test robot <lkp@intel.com>
Closes: https://lore.kernel.org/oe-kbuild-all/202509192138.fx3H6NzG-lkp@intel.com/
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <c3b9de17-7cd8-4968-9872-cbe2607a7143@gmail.com>
In brief "Extended error information" section, details on error
condition is referred to ftrace docs, which is written in :file:
directive instead of a proper cross-reference. Convert it.
Reviewed-by: Tom Zanussi <zanussi@kernel.org>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250916054202.582074-7-bagasdotme@gmail.com>
Use Sphinx note:: directive for the introductory note at the beginning
of docs, instead of aligned-text paragraph that renders as definition
list.
Reviewed-by: Tom Zanussi <zanussi@kernel.org>
Reviewed-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250916054202.582074-6-bagasdotme@gmail.com>
Section heading for sched_waking histogram is shown as normal paragraph
instead due to codeblock marker for the following diagram being in the
same line as the section underline. Separate them.
Fixes: daceabf1b4 ("tracing/doc: Fix ascii-art in histogram-design.rst")
Reviewed-by: Tom Zanussi <zanussi@kernel.org>
Reviewed-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250916054202.582074-5-bagasdotme@gmail.com>
Diagram explanation text is supposed to be interleaved commentary
between diagram parts that are spread out, but it outputs ugly in
htmldocs due to trailing vertices as if both the explanation and the
diagram are in the same literal code block.
Trim trailing vertices.
Reviewed-by: Tom Zanussi <zanussi@kernel.org>
Reviewed-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250916054202.582074-4-bagasdotme@gmail.com>
Section numbering in subsections of "Histogram Trigger Command" sections
is inconsistent in order. In particular, "'hist' trigger examples" is
erroneously numbered as 6.2, which is a leftover from b8df4a3634
("tracing: Move hist trigger Documentation to histogram.txt").
Fix the order.
Reviewed-by: Tom Zanussi <zanussi@kernel.org>
Reviewed-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250916054202.582074-3-bagasdotme@gmail.com>
Replace incorrect plural form "busses" with "buses" in
multiple documentation files under "Documentation/driver-api".
Signed-off-by: Marneni PoornaChandu <Poornachandumarneni@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250917220430.5815-1-Poornachandumarneni@gmail.com>
Use reST syntax for admonitions (notes and custom admonition
for gotcha).
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250909063744.30053-4-bagasdotme@gmail.com>
Properly indent 8th step text (as enumerated list item) to be inline
with other steps.
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250909063744.30053-3-bagasdotme@gmail.com>
These last two enumerated sections headings are in normal paragraphs,
making both sections merged into "Loading" section instead.
Add the headings.
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250909063744.30053-2-bagasdotme@gmail.com>
Finish top level sysfs directory descriptions for block, class, firmware,
hypervisor, kernel, and power. Did not write one for net directory. See
commit bc3a88431672 ("docs: filesystems: sysfs: remove top level sysfs net
directory")
Signed-off-by: Alex Tran <alex.t.tran@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250902023039.1351270-1-alex.t.tran@gmail.com>
Change sysfs bus/devices and dev directory descriptions to
provide more verbose information about the specific symlink
destination the devices point to.
Signed-off-by: Alex Tran <alex.t.tran@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250902023039.1351270-2-alex.t.tran@gmail.com>
The net/ directory is not present as a top level sysfs directory
in standard Linux systems. Network interfaces can be accessible
via /sys/class/net instead.
Signed-off-by: Alex Tran <alex.t.tran@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250902023039.1351270-3-alex.t.tran@gmail.com>
Add a newline after both subheadings to avoid any ambiguous formatting,
especially in htmldocs. Without the newline, subheadings are rendered as
part of the following paragraphs, which can be confusing to read.
Suggested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Thorsten Blum <thorsten.blum@linux.dev>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250916222944.2547948-2-thorsten.blum@linux.dev>
The regex in this block of code makes no sense, and a quick test shows that
it never matches anything; simply delete the code.
No output changes.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add some more comments to dump_function(), add some comments, and trim out
an unneeded duplicate output_declaration() call.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The logic to handle macros is split in dump_function(); bring it all
together into a single place and add a comment saying what's going on.
Remove the unneeded is_define_proto variable, and tighten up the code
a bit.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The regexes for the parsing of function prototypes were more complicated
than they needed to be and difficult to understand -- at least, I spent a
fair amount of time bashing my head against them. Simplify them, and add
some documentation comments as well.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The is_define_proto case in dump_function() uses a regex with an empty
capture group - () - that has no use; just take it out.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The "name" regex in dump_function() includes both the tilde and colon
characters, but neither has any place in function prototypes. Remove the
characters, after which the regex simplifies to "\w+"
No output changes.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Both functions and structs are passed through a set of regex-based
transforms, but the two were structured differently, despite being the same
thing. Create a utility function to apply transformations and use it in
both cases.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Move these definitions to file level, where they are executed once, and
don't clutter the function itself.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The handling of untyped parameters involved a number of redundant tests;
restructure the code to remove them and be more compact.
No output changes.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The special case for __cacheline_group_begin/end() can be handled by just
adding another pattern to the struct_prefixes, eliminating the need for a
special case in push_parameter().
One change is that these annotations no longer appear in the rendered
output, just like all the other annotations that we clean out.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Currently, LKMM docs are not included in any of kernel documentation
books.
Commit e40573a43d ("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>
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>
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.
Link: https://lore.kernel.org/all/CAHk-=wh5AyuvEhNY9a57v-vwyr7EkPVRUKMPwj92yF_K0dJHVg@mail.gmail.com/
Cc: Linus Walleij <linus.walleij@linaro.org>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Linus Walleij <linus.walleij@linaro.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <87segwyc3p.fsf@trenco.lwn.net>
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>
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.
Add a new script and a new documentation 'make' target,
htmldocs-redirects.
This will generate HTML stub files in the HTML documentation output
directory that redirect the browser to the new path.
Suggested-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250905144608.577449-4-vegard.nossum@oracle.com>
This is the result of running:
scripts/documentation-gen-renames.py --rev v6.17-rc3 > Documentation/.renames.txt
This file records renames in the Documentation/ directory so that we
can use it to quickly generate HTML redirects from removed paths.
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250905144608.577449-3-vegard.nossum@oracle.com>
Add a new script that wraps git to trawl the repository history for
renames of .rst files in the Documentation/ directory.
Example usage:
tools/docs/gen-renames.py --rev v6.17-rc3 > Documentation/.renames.txt
The output format is simply:
<old path> SPACE <new path> NEWLINE
where neither <old path> nor <new path> contain the Documentation/
prefix or the .rst suffix. The file is sorted alphabetically.
We can suggest rerunning the script for future renames (and squash the
resulting change) or rerun it periodically to keep the file up to date.
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250905144608.577449-2-vegard.nossum@oracle.com>
Commit e9bb627561 ("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 d8fb03e1ea ("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: e9bb627561 ("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>
Most of the information in the first paragraph of the
Introduction/Credits section is outdated.
Documentation update suggestions should go to documentation maintainers
listed in MAINTAINERS. Remove misleading contact information.
Signed-off-by: Baruch Siach <baruch@tkos.co.il>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/cb4987a16ed96ee86841aec921d914bd44249d0b.1756294647.git.baruch@tkos.co.il
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.
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250830170808.3911151-1-vegard.nossum@oracle.com
Corrected a few spelling mistakes to improve the readability.
Signed-off-by: Ranganath V N <vnranganath.20@gmail.com>
Acked-by: Rob Herring (Arm) <robh@kernel.org>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250902193822.6349-1-vnranganath.20@gmail.com
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.
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/all/20250901142639.4de35a11@canb.auug.org.au/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/da91980ce42f31730dc982920167b2757b9d2769.1756732363.git.mchehab+huawei@kernel.org
