linux/Documentation/sphinx, branch v6.17

sphinx: kernel_abi: fix performance regression with O=

2025-07-24T14:36:17Z

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 [OUTDATED] Added: set() Changed: {'abi-obsolete', 'abi-removed', 'abi-stable-files', 'abi-obsolete-files', 'abi-stable', 'abi', 'abi-removed-files', 'abi-testing-files', 'abi-testing', 'gpio/index', 'gpio/obsolete'} Removed: set() All docs count: 385 Found docs count: 385 real 0m11,324s user 0m15,783s sys 0m1,164s 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 Reported-by: Akira Yokosawa Closes: https://lore.kernel.org/linux-doc/c174f7c5-ec21-4eae-b1c3-f643cca90d9d@gmail.com/ Signed-off-by: Mauro Carvalho Chehab Tested-by: Akira Yokosawa Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/e25673d87357457bc54ee863e97ff8f75956580d.1752752211.git.mchehab+huawei@kernel.org

docs: kdoc: Remove a Python 2 comment

2025-07-08T14:06:25Z

We no longer support Python 2 in the docs build chain at all, so we certainly do not need to admonish folks to keep this file working with it. Cc: Jani Nikula Reviewed-by: Mauro Carvalho Chehab Acked-by: Jani Nikula Tested-by: Akira Yokosawa Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250703184403.274408-7-corbet@lwn.net

docs: sphinx: add missing SPDX tags

2025-06-25T18:39:17Z

Several Sphinx extensions and tools are missing SPDX tags. Add them. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/1a62226c5fe524eb87bdb80b33bc7ec880a68880.1750585188.git.mchehab+huawei@kernel.org

docs: sphinx: add a file with the requirements for lowest version

2025-06-25T18:22:48Z

Those days, it is hard to install a virtual env that would build docs with Sphinx 3.4.3, as even python 3.13 is not compatible anymore with it. /usr/bin/python3.9 -m venv sphinx_3.4.3 . sphinx_3.4.3/bin/activate pip install -r Documentation/sphinx/min_requirements.txt Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/e38a44ee64ebfa37eac5f64e47af51c7ac051d5a.1750571906.git.mchehab+huawei@kernel.org

docs: sphinx: avoid using the deprecated node.set_class()

2025-06-21T19:18:03Z

Docutils emits a deprecation warning when the set_class() element method is used; that warning disappears into the ether, but it also causes a crash with docutils 0.19. Avoid the deprecated function and just append directly to the "classes" attribute like the documentation says instead. Reported-by: Akira Yokosawa Tested-by: Akira Yokosawa Closes: https://lore.kernel.org/de7bae91-3200-481f-9db2-c0dc382c91dd@gmail.com/ Fixes: d6d1df92c25f ("docs: automarkup: Mark up undocumented entities too") Signed-off-by: Jonathan Corbet

docs: automarkup: Mark up undocumented entities too

2025-06-09T20:43:09Z

The automarkup code generates markup and a cross-reference link for functions, structs, etc. for which it finds kerneldoc documentation. Undocumented entities are left untouched; that creates an inconsistent reading experience and has caused some writers to go to extra measures to cause the markup to happen. Mark up detected C entities regardless of whether they are documented. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

docs: automarkup: Remove some Sphinx 2 holdovers

2025-06-09T20:42:38Z

Remove a few declarations that are no longer doing anything now that we have left Sphinx 2 behind. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

docs: kerneldoc.py: simplify exception handling logic

2025-05-21T09:53:40Z

Get rid of logger.verbose() which is causing the logger to not work. Also, instead of having try/except everywhere, place them on a common place. While here, get rid of some bogus logs. Signed-off-by: Mauro Carvalho Chehab Acked-by: Akira Yokosawa Signed-off-by: Jonathan Corbet Message-ID:

docs: Sphinx: kerneldoc: only initialize kernel-doc classes once

2025-04-28T23:28:14Z

Instead of re-creating the objects every time, initialize it just once. This allows caching previously parsed objects. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID:

docs: sphinx: kerneldoc: Use python class if available

2025-04-21T16:39:18Z

Better integrate with the new kernel-doc tool by calling the Python classes directly if KERNELDOC=scripts/kernel-doc.py. This way, warnings won't be duplicated anymore, as files will be parsed only once. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/1556a6c005d8e0fafa951f74725e984e1c7459bf.1744685912.git.mchehab+huawei@kernel.org