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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Tue, 20 May 2025 17:23:30 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> On Tue, 20 May 2025 09:50:37 +0200, Mauro Carvalho Chehab wrote:
> > Hi Randy,
> > 
> > Em Mon, 19 May 2025 22:55:08 -0700
> > Randy Dunlap <rdunlap@infradead.org> escreveu:
> >   
> [...]
> 
> >> Traceback
> >> =========
> >>
> >>       File "/usr/lib/python3.13/site-packages/sphinx/util/parallel.py", line 137, in _join_one
> >>         raise SphinxParallelError(*result)
> >>     sphinx.errors.SphinxParallelError: KeyError: '../drivers/gpio/gpiolib-acpi.c'
> >>
> >> and then it's finished (not a normal finish).
> >> So IMHO this patch is not sufficient.  
> > 
> > Well, on next-20250516:
> > 
> > 	$ ls drivers/gpio/gpiolib-acpi.c
> > 	ls: cannot access 'drivers/gpio/gpiolib-acpi.c': No such file or directory
> > 
> > Avoiding the script to abort is a matter of adding a try/except
> > block at kerneldoc.py, but I'd say that, if an include file (or any other
> > file needed for the build) is not found, "make" should abort anyway for
> > the affected target (Kernel compilation or when doc building).  
> 
> Interesting ...
> 
> So, it sounds to me you think you have the right to break Stephen's (and
> possibly other devs') workflow of test-building kernel docs, aren't you?
> 
> I don't buy such an argument.
> 
> An innocent typo in pathname somewhere in the doc tree deserves a friendly
> warning at most, not a fatal crash within Sphinx.  That would need another
> run of "make htmldocs" after fixing the fatal error to see for other
> innocuous warnings.

If by "innocent typo" you mean removing/renaming/moving a file from
the Kernel tree without updating Makefiles, or adding them with wrong
names, then yes: I do think this should be fatal for the affected "make" 
targets. The quickest such build issues are caught, the best for everyone.

Yet, this is is a separate discussion: if there are bugs at the doc
build system, they should be fixed. In this specific case, the missing
file produces a KeyError when the messages that were supposed to be
generated by it aren't stored on a dict. I sent already some patches
addressing it:

	https://lore.kernel.org/linux-doc/cover.1747730982.git.mchehab+huawei@kernel.org/T/#t

Plus the logger fix to prevent Sphinx to suppress warnings/errors:
	https://lore.kernel.org/linux-doc/cover.1747719873.git.mchehab+huawei@kernel.org/T/#t

> 
> And your change has no effect on exposing those innocuous warnings.
> 
> On current docs-next + your change above, running:
> 
>     make cleandocs; make KERNELDOC=$PWD/scripts/kernel-doc.pl htmldocs
> 
> produces these 3 warnings:
> 
> ----------------------------------------------------------------------
> ./drivers/gpu/drm/amd/include/amd_shared.h:369: warning: Incorrect use of kernel-doc format:          * @DC_HDCP_LC_ENABLE_SW_FALLBACK If set, upon HDCP Locality Check FW
> ./drivers/gpu/drm/amd/include/amd_shared.h:369: warning: Incorrect use of kernel-doc format:          * @DC_HDCP_LC_ENABLE_SW_FALLBACK If set, upon HDCP Locality Check FW
> ./drivers/gpu/drm/amd/include/amd_shared.h:373: warning: Enum value 'DC_HDCP_LC_ENABLE_SW_FALLBACK' not described in enum 'DC_DEBUG_MASK'
> ----------------------------------------------------------------------
> 
> , while running:
> 
>     make cleandocs; make htmldocs
> 
> or:
> 
>     make cleandocs; make KERNELDOC=$PWD/scripts/kerneldoc htmldocs
> 
> doesn't produce them.

Testing here with next-20250516:

	$ ./scripts/kernel-doc.pl -Wall -none ./drivers/gpu/drm/amd/include/amd_shared.h
	$

	$ ./scripts/kernel-doc.py -Wall -none ./drivers/gpu/drm/amd/include/amd_shared.h
	$

Also, if I rename the value 'DC_HDCP_LC_ENABLE_SW_FALLBACK_XXX',
both produces identical warnings:

	$ ./scripts/kernel-doc.pl -Wall -none ./drivers/gpu/drm/amd/include/amd_shared.h
	./drivers/gpu/drm/amd/include/amd_shared.h:373: warning: Enum value 'DC_HDCP_LC_ENABLE_SW_FALLBACK_XXX' not described in enum 'DC_DEBUG_MASK'
	./drivers/gpu/drm/amd/include/amd_shared.h:373: warning: Excess enum value 'DC_HDCP_LC_ENABLE_SW_FALLBACK' description in 'DC_DEBUG_MASK'

	$ ./scripts/kernel-doc.py -Wall -none ./drivers/gpu/drm/amd/include/amd_shared.h
	Warning: ./drivers/gpu/drm/amd/include/amd_shared.h:372 Enum value 'DC_HDCP_LC_ENABLE_SW_FALLBACK_XXX' not described in enum 'DC_DEBUG_MASK'
	Warning: ./drivers/gpu/drm/amd/include/amd_shared.h:372 Excess enum value '%DC_HDCP_LC_ENABLE_SW_FALLBACK' description in 'DC_DEBUG_MASK'

So, it sounds to me that things are the way they're expected,
after applying both series.

Regards,
Mauro