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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <590981da-4d37-464f-a52e-ba163d3ecbc5@gmail.com>
Date: Tue, 20 May 2025 17:23:30 +0900
From: Akira Yokosawa <akiyks@...il.com>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
 Randy Dunlap <rdunlap@...radead.org>
Cc: Jonathan Corbet <corbet@....net>,
 Andy Shevchenko <andriy.shevchenko@...ux.intel.com>,
 Nicolas Schier <nicolas.schier@...ux.dev>,
 Stephen Rothwell <sfr@...b.auug.org.au>, linux-doc@...r.kernel.org,
 linux-kbuild@...r.kernel.org, linux-kernel@...r.kernel.org,
 Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH 1/1] docs: kerneldoc.py: don't use Sphinx logger

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@...radead.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