Re: linux-next: build failure after merge all the trees

[Akira Yokosawa <akiyks@gmail.com>]

[+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@canb.auug.org.au> 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.

Am I asking you something unreasonable?

Thanks,
Akira

>                           As kernel-doc is now fully an Sphinx extension,
> it now signalizes to Sphinx that the build has failed.
> 
> Yet, it should have produced some warnings. Maybe we need to specify a
> different log level with Sphinx to make it happen. I'll double check it
> and send a fix later on to kernel-doc.
> 
> Thanks,
> Mauro