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: <20250912102813.6ea711ca@foz.lan>
Date: Fri, 12 Sep 2025 10:28:13 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: Jani Nikula <jani.nikula@...ux.intel.com>, 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 Thu, 11 Sep 2025 07:38:56 -0600
Jonathan Corbet <corbet@....net> escreveu:

> 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...

The big advantage of intersphinx is for PDF and LaTeX output, as
this is the only way to have cross-references there.

It is also good for subsystem-specific books (or "sub-"books) like:

	- Documentation/admin-guide/media/
	- Documentation/driver-api/media/
	- Documentation/userspace-api/media/

Right now, we create a single book with all those tree, but I would
prefer to build each of them as separate units, as they are for separated
audiences, but only if cross-references will be solved in a way that
html and pdf docs will point to the other books stored at linuxtv.org.

For html, this won't be any different, in practice, from what we have,
but for PDF and ePub, this would mean smaller books.

Thanks,
Mauro