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

[Akira Yokosawa <akiyks@gmail.com>]

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.

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.

Sorry, but I believe you have run out of time.

And let me remind you of the expectation for backward-compatibility widely
accepted our community.

Akira