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

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

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