Em Tue, 20 May 2025 17:23:30 +0900 Akira Yokosawa <akiyks@xxxxxxxxx> 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@xxxxxxxxxxxxx> 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@xxxxxxxxxx/T/#t Plus the logger fix to prevent Sphinx to suppress warnings/errors: https://lore.kernel.org/linux-doc/cover.1747719873.git.mchehab+huawei@xxxxxxxxxx/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
