Message-ID: <e76e4f31-dc95-4d79-a922-7f7d1b68417f@gmail.com>
Date: Wed, 24 Sep 2025 16:03:59 +0900
From: Akira Yokosawa <akiyks@...il.com>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: linux-kernel@...r.kernel.org,
 Linux Doc Mailing List <linux-doc@...r.kernel.org>,
 Jonathan Corbet <corbet@....net>, Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH 0/1] sphinx-build-wrapper: add support for skipping
 sphinx-build

On Mon, 22 Sep 2025 14:23:30 +0200, Mauro Carvalho Chehab wrote:
> Em Mon, 22 Sep 2025 20:30:40 +0900
> Akira Yokosawa <akiyks@...il.com> escreveu:
> 
>> On Sun, 21 Sep 2025 11:13:24 +0200, Mauro Carvalho Chehab wrote:
>>> Hi Jon,
>>>
>>> This patch adds support for not running sphinx-build at the wrapper
>>> tool. It was requested by Akira, who wanted to be able to ignore
>>> Sphinx errors during latex build and still try to build PDF.  
>>
>> Thank you for trying to figure out my intention.
>> However, you failed to see the point.
>>
>>>
>>> This patch is against docs/build-script and applies after the 3 patch
>>> series I sent yesterday:
>>>
>>>     https://lore.kernel.org/linux-doc/cover.1758361087.git.mchehab+huawei@kernel.org/
>>>
>>>
>>> While Akira's original intention is to have pdfdocs target depend on
>>> latexdocs, IMO, this is overkill, as probably only Akira and a couple
>>> of other developers might want to have such behavior.  
>>
>> I think it is only you who don't want such behavior.
> 
> Whom else wants to use "make -i" to skip failed latexdocs build and
> still do pdf builds? For what reason?

Hmm, looks like you were suffered from context mismatch.

My message you tried to understand (archived at:

    https://lore.kernel.org/5031e0c4-f17e-41b8-8955-959989e797f2@gmail.com/

) started this way:

    Hi, (just got v8, but sending anyway ...),

, and the message assumed the "make pdfdocs" behavior of v7.

At the time, I thought it was what you had intended and it looked as though
you wanted latexmk/xelatex to continue running as much as possible ignoring
any intermediate errors.

You have since fixed the missed exception handling at the latexdocs phase,
but your rapid respins of this series simply overwhelmed me and I have
failed to see "make pdfdocs" now gives up at latexdocs error.

My intention of mentioning GNU Make's options of -i, -k, etc. in the message
was to show you that the make--sub-make scheme is so flexible and it can
even emulate the buggy behavior of then sphinx-build-wrapper.

In normal cases, I won't use any of those options.
But as a human developer, I sometimes use them when I observe build errors
somewhere in "make pdfdocs".

> 
>>> See, after all changes, the makefile rule for *all* doc build targets
>>> is simple:
>>>
>>>         $(Q)@$(srctree)/tools/docs/sphinx-pre-install --version-check
>>>         +$(Q)$(PYTHON3) $(BUILD_WRAPPER) $@ \
>>>                 --sphinxdirs="$(SPHINXDIRS)" $(RUSTDOC) \
>>>                 --builddir="$(BUILDDIR)" --deny-vf=$(FONTS_CONF_DENY_VF) \
>>>                 --theme=$(DOCS_THEME) --css=$(DOCS_CSS) --paper=$(PAPER)
>>>
>>> After applying patch 1 from this series, it is really easy to replicate 
>>> "make -i" by writing a small script that does:
>>>
>>> 	tools/docs/sphinx-pre-install --version-check	
>>> 	tools/docs/sphinx-build-wrapper latexdocs || echo "LaTeX build failed, but we'll try build PDF anyway"
>>> 	tools/docs/sphinx-build-wrapper -s pdfdocs
>>>   
>>
>> Hello?
>>
>> You are the one who is changing the way "make pdfdocs" behaves.
> 
> It doesn't change. if latex is not built, it won't try to build
> PDF files, just like before.

Didn't you mean "if latexdocs is not build"?
Yes, I now see this is the current behavior.

> 
> See, for almost all targets, docs build is a two-step procedure. That
> includes htmldocs as well, as it requires a post-build step to copy
> css and static files. Right now, the logic is hidden inside complex
> make macros.
> 
> The new logic place the target-dependent extra steps on separate functions
> which are now properly documented, executing them only if the first
> step works.
> 
> With the "-s" parameter, one can skip the first step, running only
> the second one.
> 
>> All I want is to restore the current behavior, without any need to
>> use such an ad-hoc script.
> 
> Huh?
> 
> You said you want to be able to do just the reverse: to ignore
> failures at latex build ("make -i").

No, as I said above, I don't want it in most cases.
But in rare occasions, I might want it.  That depends on the situation
at hand.

>                                       If you want to have exactly
> the same behavior, you don't need anything.
> 
>> Sorry, but I think I have to NAK this.
>>
>> Furthermore, your "cleanup" is obfuscating the very fact that "pdfdocs"
>> needs a successful "latexdocs" stage.
>>
>> I believe Documentation/Makefile is the right place to describe it.
> 
> If you want to propose such change, be my guest. As I said, *I* won't propose
> it, as IMO it is a bad idea, but if you want, feel free to submit a patch 
> after this one similar to:
> 
> 	-htmldocs mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
> 	+htmldocs mandocs infodocs texinfodocs latexdocs epubdocs xmldocs linkcheckdocs:
> 	+
> 	+pdfdocs: latexdocs
> 	+        +$(Q)$(PYTHON3) $(BUILD_WRAPPER) $@ -s \
> 	+                --sphinxdirs="$(SPHINXDIRS)" \
> 	+                --builddir="$(BUILDDIR)" --deny-vf=$(FONTS_CONF_DENY_VF) \
> 	+                --paper=$(PAPER)
> 
> and let's discuss its pros/cons in separate.

OK. This looks like the way forward to me.

I'll prepare a patch (set) and submit it after v6.18-rc1.

In the meantime, I think we might be better off if we could root-cause
the "latexmk bug" you repeatedly claimed you had observed, without providing
any steps to reproduce.

Let me continue in another thread.
It would be far more interesting for me to (try to) figure out what you
had observed.

Thanks,
Akira

Powered by blists - more mailing lists