Message-ID: <6hhhn5go2yb7ecdrqtuti23i6pfgckqbdk5nhuhn2ijrhmvvmw@awswbm3tvmwp>
Date: Fri, 12 Sep 2025 16:50:36 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Akira Yokosawa <akiyks@...il.com>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>, corbet@....net, 
	jani.nikula@...ux.intel.com, linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, 
	tmgross@...ch.edu
Subject: Re: [PATCH v4 08/19] tools/docs: sphinx-build-wrapper: add a wrapper
 for sphinx-build

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:
> > Em Fri, 12 Sep 2025 19:15:44 +0900
> > Akira Yokosawa <akiyks@...il.com> escreveu:
> > 
> >> [-CC: rust people and list]
> >>
> >> OK, Looks like I have to bite.
> >>
> >> On Wed, 10 Sep 2025 15:33:34 +0200, Mauro Carvalho Chehab wrote:
> >> [...]
> >>
> >>> The current approach of using LaTeX for PDF is dirty:
> >>>
> >>> - Sphinx can't produce a LaTeX file from the Kernel trees without
> >>>   hundreds of warnings;
> >>> - latexmk hides some of them, but even it just one warning is reported,
> >>>   the return status is not zero.  
> >>
> >> This sounds interesting to me.
> >> As far I remember, I have never seen such strange results of latexmk
> >> under build envs where all the necessary packages are properly installed.
> > 
> > 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).

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

On my test containers, all docs were built even on Fedora.

Yet, the issue that forced us to add "|| exit" hack to ignore PDF
build errors is not new. As I pointed, at least since 2017 we
have a hack due to that our Makefile, but I guess we had an older
hack as well.

I dunno the exact conditions, but depending on latex version, distro, 
if the computer is in bad mood, if it is rainning - or whavever other
random condition - even when all PDF docs are built, make pdf inside
output/latex may return non-zero, for warnings. Maybe it could be
also related of using latexmk or calling xelatex directly.

If I recall corretly, we added latexmk to fix some of such build
issues.

-

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");
- 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.

-- 
Thanks,
Mauro

Powered by blists - more mailing lists