linux.git/Documentation/sphinx, branch v6.16

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

docs: extensions: don't use utf-8 syntax for descriptions

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

None of the descriptions at the Sphinx extensions are using
non-ascii characters, so no need to place them under u"""
notation.

Also, according with:
	https://docs.python.org/3/deprecations/pending-removal-in-3.16.html

the 'u' format code is scheduled to be removed in Python 3.16.

So, let's just use """.

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