Re: [PATCH v4 08/19] tools/docs: sphinx-build-wrapper: add a wrapper for sphinx-build

[Akira Yokosawa <akiyks@gmail.com>]

On Fri, 12 Sep 2025 16:50:36 +0200, Mauro Carvalho Chehab wrote:
> On Fri, Sep 12, 2025 at 11:03:43PM +0900, Akira Yokosawa wrote:
>> On Fri, 12 Sep 2025 13:04:20 +0200, Mauro Carvalho Chehab wrote:
[...]

>>> I saw it here on multiple distros including Fedora (which is the one
>>> I use on my desktop). Media jenkins CI running on Debian always suffered
>>> from such issues, up to the point I started ignoring pdf build results.
>>>
>>
>> So please provide exact steps for me to see such errors.
>
> Sorry, but I don't have enough time to try reproducing it again
> (plus, I'm ran out of disk space on my /var partition forcing me to
> reclaim the space used by my test containers).

There is no urgency on my side.  Please take your time.

>
>>
>> I don't have any issues after strictly following the suggestions from
>> sphinx-pre-install under Fedora.
>>
>> I even invoked [...]/output/latex/Makefile manually after running
>> "make latexdocs" by:
>>
>>   - cd [...]/output/latex/
>>   - make PDFLATEX="latexmk -xelatex" LATEXOPTS="-interaction=batchmode -no-shell-escape" -j6 -O all
>>
>> , and all the PDFs were built without any issues.
>>
>> Quite puzzling ...
>>
>> Or does your Fedora have some Noto CJK variable fonts installed?
>
> On my main desktop, yes, that's the case: it currently has some
> Noto CJK fonts installed. I wasn't aware about such issues
> with Fedora until today, when I noticed your check script.
>

Good. That should be a step forward, I guess.

I know you have repeatedly said it is not the purpose of this series
to fix those issues in your images, but I have an impression that it is
closely related to testing sphinx-pre-install, and the objective of this
series is to make the testing/debugging of sphinx-pre-install easier for
you.

But, at least for me, the behavior you want for "pdfdocs" is not
ideal for regular testing of .rst and kernel-doc changes in kernel
source side.  I want "make pdfdocs" to give up earlier rather than later.
It should leave relevant info near the bottom of terminal log.

Now, here are my responses to your arguments:

> In any case, this changeset fix it on several ways:
> 
> - A failure while building one pdf doesn't prevent building other
>   files. With make, it may stop before building them all (if we drop
>   the "|| exit");

Didn't you mean "(if we keep the "|| exit"); ???

If you drop the "|| exit", which will cause false-negatives.

And you are going to test every PDFs at the final stage of pdfdocs
to catch such false-positives.

Sounds like a plan.

> - It prints a summary reporting what PDF files were actually built,
>   so it is easy for the developer to know what broke (and it is
>   also easily parsed by a CI);
> - The return code is zero only if all docs were built.

I agree this is an improvement, but if we get rid of the loop construct
in the Makefile, we can forget about said false-negatives, can't we? 


How about something like the following approach?

Let's think of SPHINXDIRS="admin-guide core-api driver-api userspace-api"

In this case "make latexdocs" will generate

    output/admin-guide/latex/
    output/core-api/latex/
    output/driver-api/latex/
    output/userspace-api/latex/

They will have identical boiler-plate files latex builder would emit,
and subdir-specific files such as:

    output/admin-guide/latex/admin-guide.tex
                             c3-isp.dot
                             c3-isp.pdf
                             c3-isp.svg
                             conn-states-8.dot
                             conn-states-8.pdf
                             conn-states-8.svg
                             disk-states-8.dot
                             disk-states-8.pdf
                             disk-states-8.svg
                             ...
    output/core-api/latex/core-api.tex
    output/driver-api/latex/driver-api.tex
                            DOT-1e98886fceca6e25a115532f5efebb44c09dc98b.dot
                            DOT-1e98886fceca6e25a115532f5efebb44c09dc98b.pdf
                            DOT-1e98886fceca6e25a115532f5efebb44c09dc98b.svg
                            DOT-289c17ebc0291f90ccaf431961707504464a78d4.dot
                            DOT-289c17ebc0291f90ccaf431961707504464a78d4.pdf
                            DOT-289c17ebc0291f90ccaf431961707504464a78d4.svg
                            ...
    output/userspace-api/latex/userspace-api.tex
                               DOT-1e98886fceca6e25a115532f5efebb44c09dc98b.dot
                               DOT-1e98886fceca6e25a115532f5efebb44c09dc98b.pdf
                               DOT-1e98886fceca6e25a115532f5efebb44c09dc98b.svg
                               DOT-289c17ebc0291f90ccaf431961707504464a78d4.dot
                               DOT-289c17ebc0291f90ccaf431961707504464a78d4.pdf
                               DOT-289c17ebc0291f90ccaf431961707504464a78d4.svg
                               ...
                          

At a pre-processing stage of pdfdocs, you create output/latex/ and
symlink subdir-specific files needed for latexmk/xelatex into there.
(Copying them should work too.)

    output/latex/admin-guide.tex --> ../admin-guide/latex/
                 c3-isp.pdf      --> ../admin-guide/latex/
                 conn-states-8.pdf --> ../admin-guide/latex/
                 disk-states-8.pdf --> ../admin-guide/latex/
                 ...
                 core-api.tex --> ../core-api/latex/
                 driver-api.tex --> ../driver-api/latex/
                 DOT-1e98886fceca6e25a115532f5efebb44c09dc98b.pdf --> ../driver-api/latex/
                 DOT-289c17ebc0291f90ccaf431961707504464a78d4.pdf --> ../driver-api/latex/
                 ...
                 userspace-api.tex --> ../userspace-api/
                 DOT-1e98886fceca6e25a115532f5efebb44c09dc98b.pdf --> ../userspace-api/latex/
                 DOT-289c17ebc0291f90ccaf431961707504464a78d4.pdf --> ../userspace-api/latex/
                 ...

The latexmk stage would now be identical to the SPHINXDIRS="." case,
meaning it won't need the loop in the recipe.
Furthermore, post-processing would be almost the same as the default
case.
 
As a bonus, "make -j -O" will work as the same as full pdfdocs build.

If you are interested, I think I can prepare a PoC patch, probably
after v6.18-rc1.

If your sphinx-build-wrapper's latexdocs stage can be adjusted so that
said pre-processing of pdfdocs can be made unnecessary, that would be
even better.

Regards,
Akira