Em Tue, 20 May 2025 07:18:02 +0200 Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> escreveu: > Em Mon, 19 May 2025 12:33:03 -0700 > Randy Dunlap <rdunlap@xxxxxxxxxxxxx> escreveu: > > > On 5/14/25 7:33 PM, Akira Yokosawa wrote: > > > [+CC linux-doc] > > > > > > Hi, > > > > > > On Thu, 8 May 2025 14:39:11 +0200, Mauro Carvalho Chehab wrote: > > >> Em Thu, 8 May 2025 22:25:31 +1000 > > >> Stephen Rothwell <sfr@xxxxxxxxxxxxxxxx> escreveu: > > > [...] > > > > > >>> > > >>> So, I used "KERNELDOC=$(pwd)/scripts/kernel-doc.pl" and tried again. > > >>> > > >>> I got these (new) messages: > > >>> > > >>> Error: Cannot open file drivers/virt/coco/tsm-mr.c > > >>> Error: Cannot open file drivers/virt/coco/tsm-mr.c > > >>> WARNING: kernel-doc 'scripts/kernel-doc.pl -rst -enable-lineno -export drivers/virt/coco/tsm-mr.c' failed with return code 2 > > >>> > > >>> (and a few other innocuous ones) > > >>> > > >>> So your guess is good. > > >>> > > >>> It would be nice to have the Python kernel-doc fixed as well as the > > >>> devsec-tsm tree. > > >> > > >> With regards to kernel-doc, failing to build if a file is missing > > >> is the right thing to do. > > > > > > Mauro, I don't agree here. > > > > > > With the perl version of kernel-doc, a typo in a file path doesn't cause > > > a fatal error of docs build. > > > > > > kernel-doc as python class libs ends up in a fatal error. > > > > > > Here is a log of such a fatal error (on top of current docs-next with > > > intentional typo made in a pathname in one of .. kernel-doc:: > > > > > > ----------------------------------------------------------------- > > > Sphinx parallel build error! > > > > > > Versions > > > ======== > > > > > > * Platform: linux; (Linux-6.8.0-59-generic-x86_64-with-glibc2.39) > > > * Python version: 3.12.3 (CPython) > > > * Sphinx version: 8.2.3 > > > * Docutils version: 0.21.2 > > > * Jinja2 version: 3.1.6 > > > * Pygments version: 2.19.1 > > > > > > Last Messages > > > ============= > > > > > > userspace-api/gpio/gpio-get-chipinfo-ioctl .. userspace-api/media/dvb/dmx-fclose > > > > > > > > > reading sources... [ 90%] > > > userspace-api/media/dvb/dmx-fopen .. userspace-api/media/mediactl/media-controller-model > > > > > > > > > reading sources... [ 92%] > > > userspace-api/media/mediactl/media-func-close .. userspace-api/media/v4l/diff-v4l > > > > > > Loaded Extensions > > > ================= > > > > > > * sphinx.ext.mathjax (8.2.3) > > > * alabaster (1.0.0) > > > * sphinxcontrib.applehelp (2.0.0) > > > * sphinxcontrib.devhelp (2.0.0) > > > * sphinxcontrib.htmlhelp (2.1.0) > > > * sphinxcontrib.serializinghtml (2.0.0) > > > * sphinxcontrib.qthelp (2.0.0) > > > * kerneldoc (1.0) > > > * rstFlatTable (1.0) > > > * kernel_include (1.0) > > > * kfigure (1.0.0) > > > * sphinx.ext.ifconfig (8.2.3) > > > * automarkup (unknown version) > > > * maintainers_include (1.0) > > > * sphinx.ext.autosectionlabel (8.2.3) > > > * kernel_abi (1.0) > > > * kernel_feat (1.0) > > > * translations (unknown version) > > > * sphinx.ext.imgmath (8.2.3) > > > > > > Traceback > > > ========= > > > > > > File "/<...>/sphinx-8.2.3/lib/python3.12/site-packages/sphinx/util/parallel.py", line 137, in _join_one > > > raise SphinxParallelError(*result) > > > sphinx.errors.SphinxParallelError: KeyError: '/<...>/lib/bitmap-bad.c' > > > > > > > > > The full traceback has been saved in: > > > /tmp/sphinx-err-8jzxndsr.log > > > > > > To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks! > > > Please also report this if it was a user error, so that a better error message can be provided next time. > > > make[3]: *** [/<...>/Documentation/Makefile:123: htmldocs] Error 2 > > > make[2]: *** [/<...>/Makefile:1806: htmldocs] Error 2 > > > make[1]: *** [/<...>/Makefile:248: __sub-make] Error 2 > > > make[1]: Leaving directory '/<...>/my-output' > > > make: *** [Makefile:248: __sub-make] Error 2 > > > > > > ----------------------------------------------------------------- > > > > > > This would surprise innocent devs who are kindly willing to test docs build. > > > > > > I think you need to tame its behavior and make it emit a proper warning and > > > continue building docs in case of such predictable user errors. > > > > Totally agree. > > I also agree. > > The main difference between calling kernel-doc via a shell script or > via a Python class is that now errors flow via Sphinx logger class, > so they are subject to Sphinx filtering rules. > > I double-checked: the logs are produced, and you can see them with "V=1", > but Sphinx is hiding them, perhaps because of some options passed through > sphinx-build call, or because they require them to have certain types. > > A quick workaround would be to not use Sphinx logger anymore (see > enclosed). It has a side effect, though: we lose control of setting > it via V= variable, which is not good. Heh, V=1 is not actually affected by not using Sphinx logger inside the class. So, I can't see a side effect of letting the kernel-doc use directly Python logger instead of the Sphinx variant. So, I submitted the fix at: https://lore.kernel.org/linux-doc/cover.1747719873.git.mchehab+huawei@xxxxxxxxxx/T/#t As we may want to revisit it later in the future, in case Sphinx makes something more fancy there, I added a comment at the patch. Thanks, Mauro
