linux-kernel - Re: [PATCH v4 08/19] tools/docs: sphinx-build-wrapper: add a wrapper for sphinx-build

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: <20250913121825.002c8edc@foz.lan>
Date: Sat, 13 Sep 2025 12:18:25 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Vegard Nossum <vegard.nossum@...cle.com>
Cc: Jani Nikula <jani.nikula@...ux.intel.com>, Jonathan Corbet
 <corbet@....net>, Linux Doc Mailing List <linux-doc@...r.kernel.org>,
 Björn Roy Baron <bjorn3_gh@...tonmail.com>, Alex Gaynor
 <alex.gaynor@...il.com>, Alice Ryhl <aliceryhl@...gle.com>, Boqun Feng
 <boqun.feng@...il.com>, Gary Guo <gary@...yguo.net>, Trevor Gross
 <tmgross@...ch.edu>, linux-kernel@...r.kernel.org,
 rust-for-linux@...r.kernel.org
Subject: Re: [PATCH v4 08/19] tools/docs: sphinx-build-wrapper: add a
 wrapper for sphinx-build

Em Fri, 12 Sep 2025 13:34:17 +0200
Vegard Nossum <vegard.nossum@...cle.com> escreveu:

> On 12/09/2025 12:16, Jani Nikula wrote:
> >> Here, any time increase is problematic, and SPHINXDIRS play an important
> >> hole by allowing them to build only the touched documents.  
> > This is actually problematic, because the SPHINXDIRS partial builds will
> > give you warnings for unresolved references that are just fine if the
> > entire documentation gets built.  
> 
> I admit I don't have a full overview of all the problems that are being
> solved here (in existing and proposed code), but how hard would it be to
> convert the whole SPHINXDIRS thing into a Sphinx plugin that runs early
> and discards documents outside of what the user wants to build? By
> "discards" I mean in some useful way that reduces runtime compared to a
> full build while retaining some benefits of a full build (reference
> checking)?

That's not a bad idea, but I guess it is not too easy to implement - at
least inside a Sphinx plugin.

The good news is that conf.py has already a logic to ignore patterns that
could be tweaked and/or placed on a plugin.

The bad news is that existing index.rst files will now reference
non-existing docs. No idea how to "process" them to filter out
such docs. It is probably doable. See, SPHINXDIRS supports pinpointing
any directory, not just Documentation child directories. So, eventually,
such plugin would also need to "fake" the main index.rst. Now, the
question is, if we pick for instance:

	SPHINXDIRS="netlink/spec networking"

What would be the main title that would be at the main index.rst?
I suspect that, for such cases, the title of the index would need
to be manually set at the command line interface.

Another aspect is that SPHINXDIRS affect latex document lists, 
which can be problematic.

Thanks,
Mauro