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

Mauro Carvalho Chehab
2025-09-18T23:39:46Z

Em Thu, 18 Sep 2025 13:33:53 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>
> >> 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.
>
> I found myself in a similar position... it is set in
> Documentation/sphinx/load_config.py, it seems a certain Mauro added that
> in 2019 :)

LOL!

> Since then, it has seemingly been cargo-culted all over the
> place; I wonder if we really need it.

It looks to me that it have been ages since last touched load_config.py,
as it is hard to remember about its dirty secrets.... Maybe it is part
of some traumatic experiences that we shared ;-)

Anyway, looking at:
a84d9e899683 ("docs: load_config.py: avoid needing a conf.py just due to LaTeX docs")

and seeking for what we had before, you might noticed that, in the
early days, someone called Jonathan wrote patches for instance, adding
core-api docs, including this one:

commit 22917b992d3713157e759f23a5a090687d004331
Author: Jonathan Corbet <corbet@lwn.net>
Date: Wed Nov 16 16:07:02 2016 -0700

docs: Add more manuals to the PDF build

There were a few manuals that weren't being built in PDF format, but
there's no reason not to...

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

diff --git a/Documentation/core-api/conf.py b/Documentation/core-api/conf.py
index fed87ab7f486..db1f7659f3da 100644
--- a/Documentation/core-api/conf.py
+++ b/Documentation/core-api/conf.py
@@ -3,3 +3,8 @@
project = "Core-API Documentation"

tags.add("subproject")
+
+latex_documents = [
+ ('index', 'core-api.tex', project,
+ 'The kernel development community', 'manual'),
+]

there you can see that our mistic "subproject" tag was already present :-D

What happens is that, before a84d9e899683, for every single book we
wanted to build via SPHINXDIRS, a conf.py file was required.

The actual logic is a way more complex than that, but what it does is
similar to (untested):

#
# namespace comes from conf.py: loadConfig(globals())
#
def loadConfig(namespace):
if os.path.basename(os.getcwd()) != "Documentation":
config = namespace.copy()
config['tags'].add("subproject")
namespace.update(config)

(it also has some logic there for latex_documents)

On other words:

- subproject exists only on Documentation subdirs. It is basically
used to tell *.rst files that SPHINXDIRS=<subdirs>

- its goal is to run genindex when SPHINXDIRS is used to build
html documentation.

And that explains why when rust is built, it has a duplicated indexes:
neither the current docs Makefile nor sphinx-build-wrapper should be
manually adding "-t subproject".

-

That's said, as part of our doc build cleanups, IMHO we should add on
our todo to drop load_config.py, adding the missing bits on conf.py
while properly documenting it.

Thanks,
Mauro