linux-stable.git/Documentation/sphinx, branch linux-6.16.y

sphinx: kernel_abi: fix performance regression with O=

2025-08-20T16:41:22+00:00

[ Upstream commit 2b16b71a05a7f056221751b906c13f8809656b1f ]

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
Signed-off-by: Sasha Levin

docs: kerneldoc.py: simplify exception handling logic

2025-05-21T09:53:40+00:00

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:14+00:00

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:18+00:00

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

docs: automarkup: Move common logic to add and resolve xref to helper

2025-04-14T16:04:07+00:00

Several of the markup functions contain the same code, calling into
sphinx's pending_xref and resolve_xref functions to add and resolve a
cross-reference, with only a few of the parameters changed (domain,
reference type, markup content). Move this logic to its own function and
reuse it in the markup functions.

No functional change.

Signed-off-by: Nícolas F. R. A. Prado 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20250408-automarkup-resolve-xref-helper-v2-1-e0a9b8fc7fdd@collabora.com

docs: sphinx: kerneldoc: ignore "\" characters from options

2025-04-09T18:10:33+00:00

Documentation/driver-api/infiniband.rst has a kernel-doc tag
with "\" characters at the end:

	.. kernel-doc:: drivers/infiniband/ulp/iser/iscsi_iser.c
	   :functions: iscsi_iser_pdu_alloc iser_initialize_task_headers \
	        iscsi_iser_task_init iscsi_iser_mtask_xmit iscsi_iser_task_xmit \
	        iscsi_iser_cleanup_task iscsi_iser_check_protection \
	        iscsi_iser_conn_create iscsi_iser_conn_bind \
	        iscsi_iser_conn_start iscsi_iser_conn_stop \
	        iscsi_iser_session_destroy iscsi_iser_session_create \
	        iscsi_iser_set_param iscsi_iser_ep_connect iscsi_iser_ep_poll \
	        iscsi_iser_ep_disconnect

This is not handled well, as the "\" strings will be just stored inside
Sphinx options.

While the actual problem deserves being fixed, better to relax the
keneldoc.py extension to silently strip "\" from the end of strings,
as otherwise this may cause troubles when preparing arguments to
be executed by kernel-doc.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/4c652d6c57b20500c135b95294e554d9e9a97f42.1744106242.git.mchehab+huawei@kernel.org

docs: sphinx: kerneldoc: verbose kernel-doc command if V=1

2025-04-09T18:10:33+00:00

It is useful to know what kernel-doc command was used during
document build time, as it allows one to check the output the same
way as Sphinx extension does.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/a2f01590814b111e138f278e8a721024fdf2d445.1744106242.git.mchehab+huawei@kernel.org

docs: automarkup: drop legacy support

2025-02-18T20:42:46+00:00

Python 2 is already EOL for quite some time. Drop support for
it.

Also, the minimal Sphinx version is now 3.4.3. So, we can drop
support for Sphinx < 3.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/5cb57d158e42957d4bff06db38be141d849ac13b.1739254867.git.mchehab+huawei@kernel.org

docs: media: Allow creating cross-references for RC ABI

2025-02-18T20:42:46+00:00

Now that Documentation/ABI is processed by automarkup, let it
generate cross-references for RC sysfs devnodes.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/7c2f9a9970a15df8b5e3a6ecd21bcedcc8881ce1.1739254867.git.mchehab+huawei@kernel.org

scripts/kernel-doc: drop Sphinx version check

2025-02-13T18:33:33+00:00

As the current minimal supported Sphinx version is 3.4.3, drop
support for older versions.

Signed-off-by: Mauro Carvalho Chehab 
Reviewed-by: Kees Cook 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/0d002e7550476a68547ee53ad06cfd8fdcaf7c3a.1739254187.git.mchehab+huawei@kernel.org