Recent conversion of kernel-doc into python has resulted in a couple of
glitches in "make htmldocs" [1, 2, 3].

This is because the python version has not gone through extensive tests
such as fault-injection of erroneous kernel-doc comments and/or
kernel-doc:: directives.

Python kernel-doc as it is does not meet the usual expectation of
backward-compatibility with its perl predecessor.

Get back to the perl version as KENRELDOC default for now.

Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Link: https://lore.kernel.org/20250508182504.418552ef@canb.auug.org.au/ [1]
Link: https://lore.kernel.org/20250516193436.09bdf8cc@canb.auug.org.au/ [2]
Link: https://lore.kernel.org/20250516200350.63be46cd@canb.auug.org.au/ [3]
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
This one-liner is just a workaround, hence no Fixes: or Closes: tags.

Jon, it looks like we are running out of time for the upcoming merge window.
Let's take another development cycle for stabilizing kernel-doc in python.

Additional notes on glitches reported so far.

* Depending on the version of Sphinx, the crashing message can be useless
  for finding out what is going on [1, 2].
  With up-to-date Sphinx, the message even suggests a *bug* somewhere in
  Sphinx and includes a traceback to be reported as an issue at upstream
  Sphinx [4].

* The python version of kernel-doc fails to produce warnings on innocuous
  issues under Sphinx runs [3], which have been available with the perl
  version.

[4]: https://lore.kernel.org/879b49f5-7350-48e8-a84e-2c580a5b0ca8@gmail.com/
---
 Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 2a05988740a9..c2c9f5af4986 100644
--- a/Makefile
+++ b/Makefile
@@ -460,7 +460,7 @@ HOSTPKG_CONFIG	= pkg-config
 
 # the KERNELDOC macro needs to be exported, as scripts/Makefile.build
 # has a logic to call it
-KERNELDOC       = $(srctree)/scripts/kernel-doc.py
+KERNELDOC       = $(srctree)/scripts/kernel-doc.pl
 export KERNELDOC
 
 KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \

base-commit: a556bd882b9482f1b7ea00fcf07f9bc169f404c8
-- 
2.43.0

Em Tue, 20 May 2025 09:08:51 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> Recent conversion of kernel-doc into python has resulted in a couple of
> glitches in "make htmldocs" [1, 2, 3].
> 
> This is because the python version has not gone through extensive tests
> such as fault-injection of erroneous kernel-doc comments and/or
> kernel-doc:: directives.
> 
> Python kernel-doc as it is does not meet the usual expectation of
> backward-compatibility with its perl predecessor.
> 
> Get back to the perl version as KENRELDOC default for now.
> 
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Link: https://lore.kernel.org/20250508182504.418552ef@canb.auug.org.au/ [1]
> Link: https://lore.kernel.org/20250516193436.09bdf8cc@canb.auug.org.au/ [2]
> Link: https://lore.kernel.org/20250516200350.63be46cd@canb.auug.org.au/ [3]
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> This one-liner is just a workaround, hence no Fixes: or Closes: tags.
> 
> Jon, it looks like we are running out of time for the upcoming merge window.
> Let's take another development cycle for stabilizing kernel-doc in python.
> 
> Additional notes on glitches reported so far.
> 
> * Depending on the version of Sphinx, the crashing message can be useless
>   for finding out what is going on [1, 2].
>   With up-to-date Sphinx, the message even suggests a *bug* somewhere in
>   Sphinx and includes a traceback to be reported as an issue at upstream
>   Sphinx [4].
> 
> * The python version of kernel-doc fails to produce warnings on innocuous
>   issues under Sphinx runs [3], which have been available with the perl
>   version.
> 
> [4]: https://lore.kernel.org/879b49f5-7350-48e8-a84e-2c580a5b0ca8@gmail.com/
> ---
>  Makefile | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Makefile b/Makefile
> index 2a05988740a9..c2c9f5af4986 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -460,7 +460,7 @@ HOSTPKG_CONFIG	= pkg-config
>  
>  # the KERNELDOC macro needs to be exported, as scripts/Makefile.build
>  # has a logic to call it
> -KERNELDOC       = $(srctree)/scripts/kernel-doc.py
> +KERNELDOC       = $(srctree)/scripts/kernel-doc.pl

If I understood well, the only issue is with regards to Sphinx
hiding logs. If that's the case, better to apply instead just
the single-line change to make kerneldoc.py extension to not
use Sphinx own logger filters.

Thanks,
Mauro

---

[PATCH] docs: kerneldoc.py: don't use Sphinx logger

Unfortunately, currently Sphinx logger is suppressing too much, not
allowing warnings to be displayed. Disable it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index b713a2c4a615..687121300291 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -311,7 +311,7 @@ def setup_kfiles(app):
     if kerneldoc_bin and kerneldoc_bin.endswith("kernel-doc.py"):
         print("Using Python kernel-doc")
         out_style = RestFormat()
-        kfiles = KernelFiles(out_style=out_style, logger=logger)
+        kfiles = KernelFiles(out_style=out_style)
     else:
         print(f"Using {kerneldoc_bin}")