Re: [PATCH RESEND v3 00/15] Split sphinx call logic from docs Makefile

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

Em Wed, 03 Sep 2025 16:50:14 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > This series does a major cleanup at docs Makefile by moving the
> > actual doc build logic to a helper script (scripts/sphinx-build-wrapper).
> >
> > Such script was written in a way that it can be called either
> > directly or via a makefile. When running via makefile, it will
> > use GNU jobserver to ensure that, when sphinx-build is
> > called, the number of jobs will match at most what it is
> > specified by the "-j" parameter.  
> 
> So I've been playing with these a bit more, still trying to wrap my head
> around them.  I do wish that we were somehow ending up with something
> simpler than the status quo, but perhaps the problem domain just isn't
> that simple.

No, it isn't. We can do some cleanups later on by removing some env
vars, but still the sphinx-build logic we use is complex.

> > The first 3 patches do a cleanup at scripts/jobserver-exec
> > and moves the actual code to a library. Such library is used
> > by both the jobserver-exec command line and by sphinx-build-wrappper.  
> 
> These three seem OK, anyway, and could probably go in anytime.

Sure. Yet, we need them to ensure that sphinx-build-wrapper can
run jobs in parallel respecting make limits. If you prefer, you
can merge those three to reduce the number of patches I'll be
sending on the next version.

> > The change also gets rid of parallel-wrapper.sh, whose
> > functions are now part of the wrapper code.
> >
> > I added two patches at the end adding an extra target: "mandocs".
> > The patches came from a series I sent in separate with 2 patches.  
> 
> As for the rest, a couple of notes from where I am so far:
> 
> - The separation of the comments into their own patch is ... a bit
>   strange and makes the patches harder to review.  I plan to spend some
>   time looking at the end product, but still ...

Feel free to merge it after reviewing. The only reason I split it
is because you complained about the number of lines that the new
script have. With the split, it becomes clearer how much lines are
the actual code, and how much are the comments.

> - Acting on a hint from Akira, I note that "make O=elsewhere htmldocs"
>   no longer works - the output goes into Documentation/output
>   regardless.  That, I think, needs to be fixed.

Sure thing. I'll run some tests here and send a new version.

Thanks,
Mauro