Re: [PATCH v8 00/24] Split sphinx call logic from docs Makefile

Mauro Carvalho Chehab
2025-09-18T19:23:08Z

Em Thu, 18 Sep 2025 11:47:59 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>
> > Hi Jon,
> >
> > v8 contains a bug fix for ./tools/docs/check-variable-fonts.py command
> > line together with a new --deny-vf argument to it, plus addresses
> > a couple checkpatch warnings. Only 4 patches changed: patches 1, 2, 4
> > and 5.
>
> OK. I have applied this to a branch called build-script in my tree.

Thanks!

> Applying it to current docs-mw (or docs-next) was a bit of a challenge,
> due to merge conflicts with the makefiles, but I got there.
>
> This work is now merged in docs-next (and will thus show in linux-next),
> but it's not yet in docs-mw, so we're not committed to putting it into
> 6.18. My current thinking, if all goes well, is to shift it to docs-mw
> just after the merge window.

Sounds like a plan.

> It all seems to work for me, with one little oddity: the "Indices"
> section in Documentation/rust/index.rst (which is protected by the usual
> ".. only::" block) is being included in the htmldocs build, leading to a
> spurious "Indices" entry in the left column. Something about the way
> the rust directory is being build sets "subproject" maybe?

The only differences with rust is that:

1) it calls sphinx-build with:

if rustdoc:
args.extend(["-t", "rustdoc"])

where -t is:

--tag, -t TAG define tag: include "only" blocks with TAG

2) it calls rust makefile at the end of the build with:

if rustdoc:
if "MAKE" in self.env:
cmd = [self.env["MAKE"]]
else:
cmd = ["make", "LLVM=1"]

cmd += [ "rustdoc"]
if self.verbose:
print(" ".join(cmd))

try:
subprocess.run(cmd, check=True)
except subprocess.CalledProcessError as e:
print(f"Ignored errors when building rustdoc: {e}. Is RUST enabled?",
file=sys.stderr)

Both are there to mimic the original behavior, but maybe we need to
use cwd=<some_dir> to simulate the exact makefile behavior (although,
on my tests, not setting it seems to be the right choice, due
to O=build_dir).

> I haven't
> had the time to figure it out.

I don't remember anymore what "subproject" really means inside
".. only::", block, but I guess it is meant to be used when one
passes SPHINXDIRS.

Anyway, if I have to guess, I would try commenting out the "-t"
logic and see how it affects the output. If nobody steps up, I'll
try to do it probably next week, as I'm a little busy tomorrow.

Thanks,
Mauro