Em Tue, 20 May 2025 09:08:51 +0900 Akira Yokosawa <akiyks@xxxxxxxxx> 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@xxxxxxxxxxxxxxxx> > Link: https://lore.kernel.org/20250508182504.418552ef@xxxxxxxxxxxxxxxx/ [1] > Link: https://lore.kernel.org/20250516193436.09bdf8cc@xxxxxxxxxxxxxxxx/ [2] > Link: https://lore.kernel.org/20250516200350.63be46cd@xxxxxxxxxxxxxxxx/ [3] > Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx> > Cc: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> > --- > 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@xxxxxxxxx/ > --- > 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@xxxxxxxxxx> 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}")
