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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20250919013942.030544ed@foz.lan>
Date: Fri, 19 Sep 2025 01:39:42 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
 linux-kernel@...r.kernel.org, Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH v8 00/24] Split sphinx call logic from docs Makefile

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

> Mauro Carvalho Chehab <mchehab+huawei@...nel.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@....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@....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