This is a brand-new translation against
commit 2783096fb1 ("docs: submit-checklist: Expand on build tests
against different word sizes"), rather than an update of
ja_JP/SubmitChecklist, which has never updated since 2008 except for
trivial changes not involving translation.
As we now have two reST contents under the ja_JP translation,
to avoid duplicated boiler plates, split out ja_JP's own disclaimer
part into a new section and put a reference to it at the beginning of
each doc.
As there is no prospect of ja_JP to have a lot of translated docs,
keep those .rst files in the toctree of ja_JP/index.rst.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Tsugikazu Shibata <shibata@linuxfoundation.org>
Reviewed-by: Tsugikazu Shibata <shibata@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250217060132.64670-1-akiyks@gmail.com
Dongliang Mu has translated a substantial portion of kernel documentation
into Chinese, developed scripts/checktransupdate.py utility to automate
tracking of translated content updates, and actively reviewed patches.
Thus, add Dongliang Mu as a reviewer for the translations of
Chinese Documentation.
Signed-off-by: Dongliang Mu <dzm91@hust.edu.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250217043109.3571459-1-dzm91@hust.edu.cn
Add a reference to my new book, The Linux Memory Manager, an in-depth
exploration of the memory management subsystem, to
process/kernel-docs.rst.
This is not yet published, but the full draft is available on pre-order, so
it seems worthwhile adding it here. The situation is made clear in the
'notes' section.
The 'pre-release' was made available in February 2025, and full release is
scheduled for Fall 2025. The book's ISBN-13 is 978-1718504462.
The document will be updated upon release to reflect this.
Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Reviewed-by: Carlos Bilbao <carlos.bilbao@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250218154303.45595-1-lorenzo.stoakes@oracle.com
Mauro says:
This series increases the minimal requirements for Sphinx and Python, and
drop some backward-compatible code from Sphinx extension.
Looking at Sphinx release dates:
Release 2.4.0 (released Feb 09, 2020)
Release 2.4.4 (released Mar 05, 2020) (current minimal requirement)
Release 3.4.0 (released Dec 20, 2020)
Release 3.4.3 (released Jan 08, 2021)
(https://www.sphinx-doc.org/en/master/changes/index.html)
And Python release dates, we have:
Python Release date
3.5 2015-09-13 (current minimal requirement)
3.6 2016-12-23
3.7 2018-06-27
3.8 2019-10-14
3.9 2020-10-05
3.10 2021-10-04
(according with https://en.wikipedia.org/w/index.php?title=History_of_Python)
The new minimal requirements are now compatible with the toolset available on Jan, 2021,
e.g.:
- Sphinx 3.4.3;
- Python 3.9
The new Sphinx minimal requirement allows dropping all backward-compatible code
we have at kernel-doc and at Sphinx extensions.
The new Python minimal requirement also matches the current required level for
almost all scripts (*).
Those matches a 4-years old toolchain, which sounds a reasonable period
of time, as Python/Sphinx aren't required for the Kernel build.
(*) Except for a couple scripts inside tools that require python 3.10:
$ vermin -v $(git ls-files '*.py')|grep 3.10
!2, 3.10 tools/net/sunrpc/xdrgen/generators/__init__.py
!2, 3.10 tools/net/sunrpc/xdrgen/generators/program.py
!2, 3.10 tools/net/sunrpc/xdrgen/subcmds/source.py
!2, 3.10 tools/net/sunrpc/xdrgen/xdr_ast.py
!2, 3.10 tools/perf/scripts/python/mem-phys-addr.py
!2, 3.10 tools/power/cpupower/bindings/python/test_raw_pylibcpupower.py
Such scripts aren't required for Kernel builds, so it should be OK to set minimal
python version to 3.9.
The ABI documentation looks a little bit better if it starts
with the contents of the README is placed at the beginning.
Move it to the beginning of the ABI chapter. While here, improve
the README text and change the title that will be shown at the
html/pdf output to be coherent with both ABI file contents and
with the generated documentation output.
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/20250211055809.1898623-1-mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Fixed some spelling mistakes identified by misspell tool.
The example code in Documentation/driver-api/nvdimm/nvdimm.rst contained a
misspelled identifier (paramaters instead of parameters).
This typo would have caused a compilation error if copied as-is.
Signed-off-by: Aditya Dutt <duttaditya18@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250211103002.199004-1-duttaditya18@gmail.com
Kernel-doc has an obscure logic that uses an external file
to map files via a .tmp_filelist.txt file stored at the current
directory. The rationale for such code predates git time,
as it was added on Kernel v2.4.5.5, with the following description:
# 26/05/2001 - Support for separate source and object trees.
# Return error code.
# Keith Owens <kaos@ocs.com.au>
from commit 396a6123577d ("v2.4.5.4 -> v2.4.5.5") at the historic
tree:
https://git.kernel.org/pub/scm/linux/kernel/git/history/history.git/
Support for separate source and object trees is now done on a different
way via make O=<object>.
There's no logic to create such file, so it sounds to me that this is
just dead code.
So, drop it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/fd3b28dec36ba1668325d6770d4c4754414337fc.1739340170.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
As warned by get_abi.py, there are two symbols that are
defined twice:
WARNING: /sys/devices/system/cpu/cpuX/topology/physical_package_id is defined 2 times: \
/new_devel/v4l/docs/Documentation/ABI/stable/sysfs-devices-system-cpu:27; \
/new_devel/v4l/docs/Documentation/ABI/testing/sysfs-devices-system-cpu:70
WARNING: /sys/devices/system/cpu/cpuX/topology/ppin is defined 2 times: \
/new_devel/v4l/docs/Documentation/ABI/stable/sysfs-devices-system-cpu:89; \
/new_devel/v4l/docs/Documentation/ABI/testing/sysfs-devices-system-cpu:70
As the documentation at testing/sysfs-devices-system-cpu, drop
the duplicated one from stable.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/c3dce809f577584cf9aedafc6c2a0d5a9ca909ac.1739394480.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Adding company name in round brackets to From/SoB lines
is fairly common, but I don't see it documented anywhere.
Every now and then people try to add the sponsorship lines
to the commit message, fun example from this merge window:
Sponsored by: The FreeBSD Foundation
from commit 2ce67f8bf1 ("wifi: iwlwifi: mvm: fix iwl_ssid_exist()
check"). Better format would be:
Author: Miri Korenblit (FreeBSD Foundation) <...
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250203174626.1131225-1-kuba@kernel.org
Mauro says:
This series replace get_abi.pl with a Python version.
I originally started it due to some issues I noticed when searching for
ABI symbols. While I could just go ahead and fix the already existing
script, I noticed that the script maintainance didn't have much care over
all those years, probably because it is easier to find Python programmers
those days.
Also, the code is complex and was not using modules or classes and
were using lots of global variables.
So, I decided to rewrite it in Python. I started with a manual conversion
for each function. Yet, to avoid future maintainership issues, I opted to
divide the main code on three classes, each on a sepaparate file.
Just like the original RFC, I opted to keep the Sphinx kernel-abi module
on three different phases:
- call get_abi.py as an exec file;
- import AbiParser on a minimal integration scenario;
- cleanup the code to avoid needing to parse line numbers from the text.
This way, if something goes wrong, it would be easier to just revert any
offending patches, It also provides a better rationale about what each
logical change is doing.
The initial patches on this series do some preparation work and
cleans some ABI symbol bugs that lack ":" delimiter.
The undefined logic is complex and has lots of magic on it.
Implement it, using the same algorithm we have at get_abi.pl. Yet,
some tweaks to optimize performance and to make the code simpler
were added here:
- at the perl version, the tree graph had loops, so we had to
use BFS to traverse it. On this version, the graph is a tree,
so, it simplifies the what group for sysfs aliases;
- the logic which splits regular expressions into subgroups
was re-written to make it faster;
- it may optionally use multiple processes to search for symbol
matches;
- it has some additional debug levels.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/1529c255845d117696d5af57d8dc05554663afdf.1739182025.git.mchehab+huawei@kernel.org
Despite being introduced on Python 3.6, the original implementation
was too limited: it doesn't accept anything but the argument.
Even on python 3.10.12, support was still limited, as more complex
operations cause SyntaxError:
Exception occurred:
File ".../linux/Documentation/sphinx/kernel_abi.py", line 48, in <module>
from get_abi import AbiParser
File ".../linux/scripts/lib/abi/abi_parser.py", line 525
msg += f"{part}\n{"-" * len(part)}\n\n"
^
SyntaxError: f-string: expecting '}'
Replace f-strings by normal string concatenation when it doesn't
work on Python 3.6.
Reported-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/41d2f85df134a46db46fed73a0f9697a3d2ae9ba.1739182025.git.mchehab+huawei@kernel.org
Sphinx logging system doesn't like warnings during module load,
as it understands that such logs are produced at the wrong time:
WARNING: while setting up extension automarkup: /sys/devices/system/cpu/cpuX/topology/physical_package_id is defined 2 times: /new_devel/v4l/docs/Documentation/ABI/stable/sysfs-devices-system-cpu:27; /new_devel/v4l/docs/Documentation/ABI/testing/sysfs-devices-system-cpu:70
WARNING: while setting up extension automarkup: /sys/devices/system/cpu/cpuX/topology/ppin is defined 2 times: /new_devel/v4l/docs/Documentation/ABI/stable/sysfs-devices-system-cpu:89; /new_devel/v4l/docs/Documentation/ABI/testing/sysfs-devices-system-cpu:70
So, use a function to allocate/process ABI files and use it to
be called at kernel_abi.py, as automarkup also needs it to
produce the right cross-references.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/b0e79dc60d556e3b39fa6774d3b7bf734b73f352.1739182025.git.mchehab+huawei@kernel.org
Now that all ABI files are handled together, we can add a feature
at automarkup for it to generate cross-references for ABI symbols.
The cross-reference logic can produce references for all existing
files, except for README (as this is not parsed).
For symbols, they need to be an exact match of what it is
described at the docs, which is not always true due to wildcards.
If symbols at /sys /proc and /config are identical, a cross-reference
will be used.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0b97a51b68b1c20127ad4a6a55658557fe0848d0.1739182025.git.mchehab+huawei@kernel.org
The get_abi.pl script is requiring some care, but it seems that
the number of changes on it since when I originally wrote it
was not too high.
Maintaining perl scripts without using classes requires a higher
efforted than on python, due to global variables management.
Also, it sounds easier to find python developer those days than
perl ones.
As a plus, using a Python class to handle ABI allows a better
integration with Sphinx extensions, allowing, for instance,
to let automarkup to generate cross-references for ABI
symbols.
With that in mind, rewrite the core of get_abi.pl in Python,
using classes, to help producing documentation. This will
allow a better integration in the future with the Sphinx
ABI extension.
The algorithms used there are the same as the ones in Perl,
with a couple of cleanups to remove redundant variables and
to help with cross-reference generation. While doing that,
remove some code that were important in the past, where
ABI files weren't using ReST format.
Some minor improvements were added like using a fixed seed
when generating ABI keys for duplicated names, making its
results reproductible.
The end script is a little bit faster than the original one
(tested on a machine with ssd disks). That's probably because
we're now using only pre-compiled regular expressions, and it
is using string replacement methods instead of regex where
possible.
The new version is a little bit more conservative when
converting text to cross-references to avoid adding them into
literal blocks.
To ensure that the ReST output is parsing all variables
and files properly, the end result was compared using diff
with the one produced by the perl script and showed no regressions.
There are minor improvements at the results, as it now
properly groups What on some special cases. It also better
escape some XREF names.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/71a894211a8b69664711144d9c4f8a0e73d1ae3c.1739182025.git.mchehab+huawei@kernel.org
