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] [thread-next>] [day] [month] [year] [list]

Message-ID: <a1333c717bb5bcea7f7c616cbf8604fa259c3158@intel.com>
Date: Thu, 11 Sep 2025 22:33:58 +0300
From: Jani Nikula <jani.nikula@...ux.intel.com>
To: Jonathan Corbet <corbet@....net>, Mauro Carvalho Chehab
 <mchehab+huawei@...nel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>, 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

On Thu, 11 Sep 2025, Jonathan Corbet <corbet@....net> wrote:
> Mauro Carvalho Chehab <mchehab+huawei@...nel.org> writes:
>
>> On Thu, Sep 11, 2025 at 01:23:55PM +0300, Jani Nikula wrote:
>>> > 1. SPHINXDIRS. It needs a lot of magic to work, both before running
>>> >    sphinx-build and after (inside conf.py);
>>> 
>>> Makes you wonder if that's the right solution to the original
>>> problem. It was added as a kind of hack, and it stuck.
>>
>> The problem is, IMHO, due to the lack of flexibility of sphinx-build:
>> It should have a way on it to do partial documentation builds.
>
> A couple of times I have looked into using intersphinx, making each book
> into an actually separate book.  The thing I always run into is that
> doing a complete docs build, with working references, would require
> building everything twice.  This is probably worth another attempt one
> of these years...

I think the main factor in that should be whether it makes sense from
overall documentation standpoint, not the technical details.

Having several books might make sense. It might even be helpful in
organizing the documentation by audiences. But having the granularity of
SPHINXDIRS with that would be overkill. And there needs to be a book to
bring them together, and link to the other books, acting as the landing
page.

I believe it should be possible to generate the intersphinx inventory
without generating the full html or pdf documentation. So I don't think
it's actually two complete docs builds. It might speed things up to have
a number of independent documentation builds.

As to the working references, IIUC partial builds with SPHINXDIRS
doesn't get that part right if there are references outside of the
designated dirs, leading to warnings.

BR,
Jani.

-- 
Jani Nikula, Intel