scripts: add origin commit identification based on specific patterns
This patch adds the functionability to smartly identify origin commit
of the translation by matching the following patterns in commit log:
1) update to commit HASH
2) Update the translation through commit HASH
If no such pattern is found, script will obey the original workflow.
sphinx: kernel_abi: fix performance regression with O=<dir>
The logic there which adds a dependency note to Sphinx cache
is not taking into account that the build dir may not be
the source dir. This causes a performance regression:
$ time make O=/tmp/foo SPHINXDIRS=admin-guide htmldocs
To get the root cause of the problem (ABI files reported as changed),
I used this changeset:
diff --git a/Documentation/conf.py b/Documentation/conf.py
index e8766e689c1b..ab486623bd8b 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -571,3 +571,16 @@ def setup(app):
"""Patterns need to be updated at init time on older Sphinx versions"""
app.connect('config-inited', update_patterns)
+ app.connect('env-get-outdated', on_outdated)
+
+def on_outdated(app, env, added, changed, removed):
+ """Track cache outdated due to added/changed/removed files"""
+ print("\n[OUTDATED]")
+ print(f"Added: {added}")
+ print(f"Changed: {changed}")
+ print(f"Removed: {removed}")
+ print(f"All docs count: {len(env.all_docs)}")
+ print(f"Found docs count: {len(env.found_docs)}")
+
+ # Just return what we have
+ return added | changed | removed
The x86-specific functions kvm_guest_{enter,exit}_irqoff() were removed
and replaced by the generic guest_state_{enter,exit}_irqoff() in commit ef9989afda73 ("kvm: add guest_state_{enter,exit}_irqoff()") and commit b2d2af7e5df3 ("kvm/x86: rework guest entry logic").
Update the references in the entry/exit handling documentation.
Cc: Thomas Gleixner <tglx@linutronix.de> Cc: Nicolas Saenz Julienne <nsaenz@amazon.com> Cc: Mark Rutland <mark.rutland@arm.com> Signed-off-by: Andrew Donnellan <ajd@linux.ibm.com> Reviewed-by: Thomas Gleixner <tglx@linutronix.de> Acked-by: Mark Rutland <mark.rutland@arm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250723075134.105132-1-ajd@linux.ibm.com
docs: fault-injection: drop reference to md-faulty
Commit 415c7451872b ("md: Remove deprecated CONFIG_MD_FAULTY") removed
the md-faulty driver, so drop the outdated reference from the
fault-injection documentation.
Add example-driven documentation for the kernel's generic linked list
data structure. This includes discussion of situations where linked
lists are likely inappropriate, and references to further reading.
docs: kernel-doc: emit warnings for ancient versions of Python
Kernel-doc requires at least version 3.6 to run, as it uses f-string.
Yet, Kernel build currently calls kernel-doc with -none on some places.
Better not to bail out when older versions are found.
Versions of Python prior to 3.7 do not guarantee to remember the insertion
order of dicts; since kernel-doc depends on that guarantee, running with
such older versions could result in output with reordered sections.
Check Python version when called via command line.
Add clarification that the printk_ratelimit_burst window resets after
printk_ratelimit seconds have elapsed, allowing another burst of
messages to be sent. This helps users understand that the rate limiting
is not permanent but operates in periodic windows.
The macros table has three columns: the second one is "an" and the
third one writes "an ioctl with ... parameters". Simplify the table
by adding heading row that indicates macro name and accepted
parameters.
Documentation: ioctl-number: Correct full path to papr-physical-attestation.h
Commit 03c9d1a5a30d93 ("Documentation: Fix description format for
powerpc RTAS ioctls") fixes Sphinx warning by chopping arch/ path
component of papr-physical-attestation.h to fit existing "Include File"
column. Now that the column has been widened just enough for that
header file, add back its arch/ path component.
Jonathan Corbet [Tue, 15 Jul 2025 19:46:42 +0000 (13:46 -0600)]
Merge branch 'kdoc-item2' into docs-mw
The kerneldoc parsing phase gathers all of the information about the
declarations of interest, then passes it through to the output phase as a
dict that is an unstructured blob of information; this organization has its
origins in the Perl version of the program. It results in an interface
that is difficult to reason about, dozen-parameter function calls, and
other ills.
Introduce a new class (KdocItem) to carry this information between the
parser and the output modules, and, step by step, modify the system to use
this class in a more structured way. This could be taken further by
creating a subclass of KdocItem for each declaration type (function,
struct, ...), but that is probably more structure than we need.
The result is (I hope) clearer code, the removal of a bunch of boilerplate,
and no changes to the generated output.
Jonathan Corbet [Thu, 10 Jul 2025 23:24:07 +0000 (17:24 -0600)]
docs: kdoc: emit a warning for ancient versions of Python
Versions of Python prior to 3.7 do not guarantee to remember the insertion
order of dicts; since kernel-doc depends on that guarantee, running with
such older versions could result in output with reordered sections.
Python 3.9 is the minimum for the kernel as a whole, so this should not be
a problem, but put in a warning just in case somebody tries to use
something older.
Jonathan Corbet [Wed, 2 Jul 2025 20:53:32 +0000 (14:53 -0600)]
docs: kdoc: clean up check_sections()
entry.sectcheck is just a duplicate of our list of sections that is only
passed to check_sections(); its main purpose seems to be to avoid checking
the special named sections. Rework check_sections() to not use that field
(which is then deleted), tocheck for the known sections directly, and
tighten up the logic in general.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Wed, 2 Jul 2025 19:17:59 +0000 (13:17 -0600)]
docs: kdoc: Regularize the use of the declaration name
Each declaration type passes through the name in a unique field of the
"args" blob - even though we have always just passed the name separately.
Get rid of all the weird names and just use the common version.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Wed, 2 Jul 2025 19:05:56 +0000 (13:05 -0600)]
docs: kdoc: Coalesce parameter-list handling
Callers to output_declaration() always pass the parameter information from
self.entry; remove all of the boilerplate arguments and just get at that
information directly. Formalize its placement in the KdocItem class.
It would be nice to get rid of parameterlist as well, but that has the
effect of reordering the output of function parameters and struct fields to
match the order in the kerneldoc comment rather than in the declaration.
One could argue about which is more correct, but the ordering has been left
unchanged for now.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Wed, 2 Jul 2025 17:12:27 +0000 (11:12 -0600)]
docs: kdoc: use self.entry.parameterlist directly in check_sections()
Callers of check_sections() join parameterlist into a single string, which
is then immediately split back into the original list. Rather than do all
that, just use parameterlist directly in check_sections().
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Wed, 2 Jul 2025 17:04:43 +0000 (11:04 -0600)]
docs: kdoc: remove the "struct_actual" machinery
The code goes out of its way to create a special list of parameters in
entry.struct_actual that is just like entry.parameterlist, but with extra
junk. The only use of that information, in check_sections(), promptly
strips all the extra junk back out. Drop all that extra work and just use
parameterlist.
No output changes.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Tue, 1 Jul 2025 22:47:59 +0000 (16:47 -0600)]
docs: kdoc: Centralize handling of the item section list
The section list always comes directly from the under-construction entry
and is used uniformly. Formalize section handling in the KdocItem class,
and have output_declaration() load the sections directly from the entry,
eliminating a lot of duplicated, verbose parameters.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Tue, 1 Jul 2025 22:21:24 +0000 (16:21 -0600)]
docs: kdoc: drop "sectionlist"
Python dicts (as of 3.7) are guaranteed to remember the insertion order of
items, so we do not need a separate list for that purpose. Drop the
per-entry sectionlist variable and just rely on native dict ordering.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Tue, 15 Jul 2025 19:20:32 +0000 (13:20 -0600)]
Merge tag 'chinese-doc-6.16-rc1' of gitolite.kernel.org:pub/scm/linux/kernel/git/alexs/linux into docs-mw
Chinese translation docs for 6.16-rc1 from Alex Shi
This is the Chinese translation subtree for 6.16-rc1. It
includes few changes:
- Updates to the process documentation
- Added translations for network and speculation docs
- Polished zh_CN/how-to.rst
The above patches have been tested by 'make htmldocs'
Jonathan Corbet [Thu, 3 Jul 2025 18:44:00 +0000 (12:44 -0600)]
docs: kdoc: rework type prototype parsing
process_proto_type() is using a complex regex and a "while True" loop to
split a declaration into chunks and, in the end, count brackets. Switch to
using a simpler regex to just do the split directly, and handle each chunk
as it comes. The result is, IMO, easier to understand and reason about.
The old algorithm would occasionally elide the space between function
parameters; see struct rng_alg->generate(), foe example. The only output
difference is to not elide that space, which is more correct.
Jonathan Corbet [Thu, 3 Jul 2025 18:43:57 +0000 (12:43 -0600)]
docs: kdoc: don't reinvent string.strip()
process_proto_type() and process_proto_function() reinventing the strip()
string method with a whole series of separate regexes; take all that out
and just use strip().
The previous implementation also (in process_proto_type()) removed C++
comments *after* the above dance, leaving trailing whitespace in that case;
now we do the stripping afterward. This results in exactly one output
change: the removal of a spurious space in the definition of
BACKLIGHT_POWER_REDUCED - see
https://docs.kernel.org/gpu/backlight.html#c.backlight_properties.
I note that we are putting semicolons after #define lines that really
shouldn't be there - a task for another day.
Qiu Yutan [Mon, 30 Jun 2025 10:56:30 +0000 (18:56 +0800)]
Docs/zh_CN: Translate alias.rst to Simplified Chinese
translate the "alias.rst" into Simplified Chinese
Update to commit 735dadf894f0("docs: networking:
Convert alias.txt to rst")
Alex Shi: Modify networking/index.rst for merge issue. Signed-off-by: Qiu Yutan <qiu.yutan@zte.com.cn> Signed-off-by: Jiang Kun <jiang.kun2@zte.com.cn> Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn> Reviewed-by: xu xin <xu.xin16@zte.com.cn> Signed-off-by: Alex Shi <alexs@kernel.org>
Wang Yaxin [Sat, 5 Jul 2025 03:08:47 +0000 (11:08 +0800)]
Docs/zh_CN: Translate netmem.rst to Simplified Chinese
translate the "netmem.rst" into Simplified Chinese.
Update the translation through commit 383faec0fd64
("net: enable driver support for netmem TX")
Signed-off-by: Wang Yaxin <wang.yaxin@zte.com.cn> Signed-off-by: Jiang Kun <jiang.kun2@zte.com.cn> Reviewed-by: xu xin <xu.xin16@zte.com.cn> Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn> Signed-off-by: Alex Shi <alexs@kernel.org>
Wang Yaxin [Sat, 5 Jul 2025 03:06:49 +0000 (11:06 +0800)]
Docs/zh_CN: Translate xfrm_proc.rst to Simplified Chinese
translate the "xfrm_proc.rst" into Simplified Chinese.
Update the translation through commit 304b44f0d5a4
("xfrm: Add dir validation to "in" data path lookup")
Signed-off-by: Wang Yaxin <wang.yaxin@zte.com.cn> Signed-off-by: Jiang Kun <jiang.kun2@zte.com.cn> Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn> Signed-off-by: Alex Shi <alexs@kernel.org>
Wang Yaxin [Sat, 5 Jul 2025 03:04:24 +0000 (11:04 +0800)]
Docs/zh_CN: Translate netif-msg.rst to Simplified Chinese
translate the "netif-msg.rst" into Simplified Chinese.
Update the translation through commit c4d5dff60f0a
("docs: networking: convert netif-msg.txt to ReST")
Signed-off-by: Wang Yaxin <wang.yaxin@zte.com.cn> Signed-off-by: Jiang Kun <jiang.kun2@zte.com.cn> Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn> Signed-off-by: Alex Shi <alexs@kernel.org>
WangYuli [Mon, 23 Jun 2025 07:19:33 +0000 (15:19 +0800)]
gitignore: allow .pylintrc to be tracked
The .pylintrc file was introduced by commit 02df8e3b333c ("docs: add a
.pylintrc file with sys path for docs scripts") to provide Python path
configuration for documentation scripts. However, the generic ".*" rule
in .gitignore causes this tracked file to be ignored, leading to warnings
during kernel builds.
Add !.pylintrc to the exception list to explicitly allow this
configuration file to be tracked by git, consistent with other
development tool configuration files like .clang-format and .rustfmt.toml.
This resolves the build warning:
.pylintrc: warning: ignored by one of the .gitignore files
Fixes: 02df8e3b333c ("docs: add a .pylintrc file with sys path for docs scripts") Signed-off-by: WangYuli <wangyuli@uniontech.com> Reviewed-by: Miguel Ojeda <ojeda@kernel.org> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/1A357750FF71847E+20250623071933.311947-1-wangyuli@uniontech.com
Bagas Sanjaya [Fri, 20 Jun 2025 10:56:44 +0000 (17:56 +0700)]
Documentation: ext4: Move inode table short docs into its own file
The short description of inode table is in bitmaps.rst alongside the
proper bitmpas documentation. The docs file is short enough that it fits
whole browser screen on desktop, which implies that when readers click
"Inode Table", they will essentially see bitmaps docs.
Bagas Sanjaya [Fri, 20 Jun 2025 10:56:43 +0000 (17:56 +0700)]
Documentation: ext4: blockgroup: Add explicit title heading
Block groups documentation has three, first-level section headings.
These headings' text become toctree entries and the first one "Layout"
becomes docs title in the output, which isn't conveying the docs
contents.
Bagas Sanjaya [Fri, 20 Jun 2025 10:56:42 +0000 (17:56 +0700)]
Documentation: ext4: atomic_writes: Demote last three sections
Last three sections of atomic block writes documentation are adorned as
first-level title headings, which erroneously increase toctree entries
in overview.rst. Demote them.
Fixes: 0bf1f51e34c4 ("ext4: Add atomic block write documentation") Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Acked-by: Theodore Ts'o <tytso@mit.edu> Acked-by: Darrick J. Wong <djwong@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250620105643.25141-5-bagasdotme@gmail.com
Bagas Sanjaya [Fri, 20 Jun 2025 10:56:40 +0000 (17:56 +0700)]
Documentation: ext4: Convert includes into toctrees
ext4 docs are organized in three master docs (overview.rst, globals.rst,
and dynamic.rst), in which these include other docs via include::
directive. These docs sturcture is better served by toctrees instead.
Convert the master docs to use toctrees.
Fixes: 0bf1f51e34c4 ("ext4: Add atomic block write documentation") Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Acked-by: Theodore Ts'o <tytso@mit.edu> Acked-by: Darrick J. Wong <djwong@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250620105643.25141-3-bagasdotme@gmail.com
Jonathan Corbet [Tue, 1 Jul 2025 21:31:11 +0000 (15:31 -0600)]
docs: kdoc; Add a rudimentary class to represent output items
This class is intended to replace the unstructured dict used to accumulate
an entry to pass to an output module. For now, it remains unstructured,
but it works well enough that the output classes don't notice the
difference.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Mon, 30 Jun 2025 17:08:32 +0000 (11:08 -0600)]
docs: kdoc: rework type prototype parsing
process_proto_type() is using a complex regex and a "while True" loop to
split a declaration into chunks and, in the end, count brackets. Switch to
using a simpler regex to just do the split directly, and handle each chunk
as it comes. The result is, IMO, easier to understand and reason about.
The old algorithm would occasionally elide the space between function
parameters; see struct rng_alg->generate(), foe example. The only output
difference is to not elide that space, which is more correct.
Add an introductory paragraph to Part Id - Streaming DMA mappings and move
the explanation of address constraints there, because it applies to all map
functions.
Clarify that streaming DMA can be used with memory which does not meet the
addressing constraints of a device, but it may fail in that case.
Make a note about SWIOTLB and link to the detailed description of it.
Do not mention platform-dependent allocation flags. The note may mislead
device driver authors into thinking that they should poke into and try to
second-guess the DMA API implementation. They definitely shouldn't.
Remove the claim that platforms with an IOMMU may not require physically
contiguous buffers. The current implementation explicitly rejects vmalloc
addresses, regardless of IOMMU.
Signed-off-by: Petr Tesarik <ptesarik@suse.com> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Marek Szyprowski <m.szyprowski@samsung.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250627101015.1600042-8-ptesarik@suse.com
Petr Tesarik [Fri, 27 Jun 2025 10:10:12 +0000 (12:10 +0200)]
docs: dma-api: remove duplicate description of the DMA pool API
Move the DMA pool API documentation from Memory Management APIs to
dma-api.rst, replacing the outdated duplicate description there.
Signed-off-by: Petr Tesarik <ptesarik@suse.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Marek Szyprowski <m.szyprowski@samsung.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250627101015.1600042-6-ptesarik@suse.com
Petr Tesarik [Fri, 27 Jun 2025 10:10:11 +0000 (12:10 +0200)]
docs: dma-api: add a kernel-doc comment for dma_pool_zalloc()
Document the dma_pool_zalloc() wrapper.
Signed-off-by: Petr Tesarik <ptesarik@suse.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Marek Szyprowski <m.szyprowski@samsung.com>
[jc: fixed up dma_pool_alloc() reference in dmapool.h] Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250627101015.1600042-5-ptesarik@suse.com
Petr Tesarik [Fri, 27 Jun 2025 10:10:10 +0000 (12:10 +0200)]
docs: dma-api: remove remnants of PCI DMA API
The wording sometimes suggests there are multiple functions for an
operation. This was in fact the case before PCI DMA API was removed, but
since there is only one API now, the documentation has become confusing.
To improve readability:
* Remove implicit references to the PCI DMA API (plurals, use of "both",
etc.)
* Where possible, refer to an actual function rather than a more generic
description of the operation.
Signed-off-by: Petr Tesarik <ptesarik@suse.com> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Marek Szyprowski <m.szyprowski@samsung.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250627101015.1600042-4-ptesarik@suse.com
Petr Tesarik [Fri, 27 Jun 2025 10:10:09 +0000 (12:10 +0200)]
docs: dma-api: replace consistent with coherent
For consistency, always use the term "coherent" when talking about memory
that is not subject to CPU caching effects. The term "consistent" is a
relic of a long-removed PCI DMA API (pci_alloc_consistent() and
pci_free_consistent() functions).
Signed-off-by: Petr Tesarik <ptesarik@suse.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Marek Szyprowski <m.szyprowski@samsung.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250627101015.1600042-3-ptesarik@suse.com
Petr Tesarik [Fri, 27 Jun 2025 10:10:08 +0000 (12:10 +0200)]
docs: dma-api: use "DMA API" consistently throughout the document
Make sure that all occurrences are spelled "DMA API" (all uppercase, no
hyphen, no underscore).
Signed-off-by: Petr Tesarik <ptesarik@suse.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Marek Szyprowski <m.szyprowski@samsung.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250627101015.1600042-2-ptesarik@suse.com
Alison Schofield [Thu, 26 Jun 2025 02:40:58 +0000 (19:40 -0700)]
docs: ABI: make the KernelVersion field optional
The KernelVersion field has limited practical value. Git history
provides more accurate tracking of when features were introduced
and target kernel versions often change during development and
merge.
Jonathan Corbet [Fri, 27 Jun 2025 18:40:00 +0000 (12:40 -0600)]
docs: kdoc: split the processing of the two remaining inline states
Now that "inline_*" are just ordinary parser states, split them into two
separate functions, getting rid of some nested conditional logic.
The original process_inline() would simply ignore lines that didn't match
any of the regexes (those lacking the initial " * " marker). I have
preserved that behavior, but we should perhaps emit a warning instead.
Jonathan Corbet [Fri, 27 Jun 2025 18:39:59 +0000 (12:39 -0600)]
docs: kdoc: remove the inline states-within-a-state
The processing of inline kerneldoc comments is a state like the rest, but
it was implemented as a set of separate substates. Just remove the
substate logic and make the inline states normal ones like the rest.
INLINE_ERROR was never actually used for anything, so just take it out.
Jonathan Corbet [Fri, 27 Jun 2025 18:39:57 +0000 (12:39 -0600)]
docs: kdoc: rework process_export() slightly
Reorganize process_export() to eliminate duplicated code, don't look for
exports in states where we don't expect them, and don't bother with normal
state-machine processing if an export declaration has been found.
Jonathan Corbet [Fri, 27 Jun 2025 18:39:54 +0000 (12:39 -0600)]
docs: kdoc: Move content handling into KernelEntry
Rather than having other code mucking around with this bit of internal
state, encapsulate it internally. Accumulate the description as a list of
strings, joining them at the end, which is a more efficient way of building
the text.
Jonathan Corbet [Fri, 27 Jun 2025 19:08:20 +0000 (13:08 -0600)]
docs: kdoc: don't reinvent string.strip()
process_proto_type() and process_proto_function() reinventing the strip()
string method with a whole series of separate regexes; take all that out
and just use strip().
The previous implementation also (in process_proto_type()) removed C++
comments *after* the above dance, leaving trailing whitespace in that case;
now we do the stripping afterward. This results in exactly one output
change: the removal of a spurious space in the definition of
BACKLIGHT_POWER_REDUCED - see
https://docs.kernel.org/gpu/backlight.html#c.backlight_properties.
I note that we are putting semicolons after #define lines that really
shouldn't be there - a task for another day.
Jonathan Corbet [Fri, 27 Jun 2025 18:23:05 +0000 (12:23 -0600)]
docs: kdoc: split the processing of the two remaining inline states
Now that "inline_*" are just ordinary parser states, split them into two
separate functions, getting rid of some nested conditional logic.
The original process_inline() would simply ignore lines that didn't match
any of the regexes (those lacking the initial " * " marker). I have
preserved that behavior, but we should perhaps emit a warning instead.
Jonathan Corbet [Fri, 27 Jun 2025 17:33:18 +0000 (11:33 -0600)]
docs: kdoc: remove the inline states-within-a-state
The processing of inline kerneldoc comments is a state like the rest, but
it was implemented as a set of separate substates. Just remove the
substate logic and make the inline states normal ones like the rest.
INLINE_ERROR was never actually used for anything, so just take it out.
Jonathan Corbet [Wed, 25 Jun 2025 23:19:40 +0000 (17:19 -0600)]
docs: kdoc: rework process_export() slightly
Reorganize process_export() to eliminate duplicated code, don't look for
exports in states where we don't expect them, and don't bother with normal
state-machine processing if an export declaration has been found.
Jonathan Corbet [Wed, 25 Jun 2025 20:51:11 +0000 (14:51 -0600)]
docs: kdoc: Move content handling into KernelEntry
Rather than having other code mucking around with this bit of internal
state, encapsulate it internally. Accumulate the description as a list of
strings, joining them at the end, which is a more efficient way of building
the text.
conf.py is missing a SPDX header and doesn't really have
a proper python coding style. It also has an obsolete
commented LaTeX syntax that doesn't work anymore.
Clean it up a little bit with some help from autolints
and manual adjustments.
scripts: test_doc_build.py: make the script smarter
Most of the time, testing the full range of supported Sphinx
version is a waste of time and resources. Instead, the best is
to focus at the versions that are actually shipped by major
distros.
For it to work properly, we need to adjust the requirements for
them to start from first patch for each distro after the
minimal supported one. The requirements were re-adjusted to
avoid build breakages related to version incompatibilities.
Such builds were tested with:
./scripts/test_doc_build.py -m -a "SPHINXOPTS=-j8" "SPHINXDIRS=networking netlink/specs" --full
Change the logic to pick by default only such versions, adding
another parameter to do a comprehensive test.
While here, improve the script documentation to make it easier
to be used.
scripts: test_doc_build.py: improve dependency list
Change the dependency list to ensure that:
- all docutils versions are covered;
- provide an explanation about the dependencies;
- set a better minimal requirement for 3.4.3.
projects / thirdparty / kernel / linux.git / log
