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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Fri, 12 Sep 2025 19:15:44 +0900
Akira Yokosawa <akiyks@gmail.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.

> I think what you are trying here is to paper over whatever bug in latexmk/
> xelatex by always ignoring their exit status.  Am I guessing right?
> 
> If that is the case, I'd rather report such an issue at upstream
> lagtexmk/xelatex.

I'm not entirely sure if this is a bug or a feature. Last time I got
one such error and did a web search, I saw similar reports explaining
the error code as if it is an expected behavior.

This is a known bug, and the current building system has a poor man
workaround for it already:

	pdfdocs: latexdocs
	       @$(srctree)/scripts/sphinx-pre-install --version-check
	       $(foreach var,$(SPHINXDIRS), \
	          $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" $(DENY_VF) -C $(BUILDDIR)/$(var)/latex || sh $(srctree)/scripts/check-variable-fonts.sh || exit; \
	          mkdir -p $(BUILDDIR)/$(var)/pdf; \
	          mv $(subst .tex,.pdf,$(wildcard $(BUILDDIR)/$(var)/latex/*.tex)) $(BUILDDIR)/$(var)/pdf/; \
	       )


see the "||" at make pipeline. The final "|| exit" makes the build
ignore pdf build errors. It is there since the beginning:

	cb43fb5775df ("docs: remove DocBook from the building system")

Thanks,
Mauro