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>
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.
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>
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.
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:
- required_arguments
- optional_arguments
- option_spec
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/a9f2eebf11c6b0c3a2e3bf42e71392cdfd2835d1.1755872208.git.mchehab+huawei@kernel.org
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/a0953af8b71e64aaf2e0ba4593ad39e19587d50a.1755872208.git.mchehab+huawei@kernel.org
