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: <mfbjzrac7q2vmvieudwagi4n6ozxl5b5ey2vy3z34bjuyweblp@s7gnmdche5cq>
Date: Mon, 15 Sep 2025 17:05:42 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jani Nikula <jani.nikula@...ux.intel.com>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>, 
	Akira Yokosawa <akiyks@...il.com>, corbet@....net, linux-doc@...r.kernel.org, 
	linux-kernel@...r.kernel.org, tmgross@...ch.edu
Subject: Re: [PATCH v4 08/19] tools/docs: sphinx-build-wrapper: add a wrapper
 for sphinx-build

On Mon, Sep 15, 2025 at 05:33:37PM +0300, Jani Nikula wrote:
> On Mon, 15 Sep 2025, Mauro Carvalho Chehab <mchehab+huawei@...nel.org> wrote:
> > On Mon, Sep 15, 2025 at 03:54:26PM +0300, Jani Nikula wrote:
> >> On Mon, 15 Sep 2025, Mauro Carvalho Chehab <mchehab+huawei@...nel.org> wrote:
> >> > IMHO, long term solution is to change SPHINXDIRS into something
> >> > like:
> >> >
> >> > 	make O=doc_build SPHINXTITLE="Media docs" SPHINXDIRS="admin-guide/media userspace-api/media driver-api/media/"
> >> >
> >> > would create something similar to this(*):
> >> >
> >> > 	doc_build/sphindirs/
> >> > 		|
> >> > 		+--> index.rst
> >> > 		+--> admin-guide -> {srcdir}/Documentation/admin-guide/media/
> >> > 		+--> usespace-api -> {srcdir}/Documentation/admin-guide/media/
> >> > 		\--> driver-api -> {srcdir}/Documentation/admin-guide/media/
> >> 
> >> So you're basically suggesting the documentation build should support
> >> cherry-picking parts of the documentation with categories different from
> >> what the upstream documentation has? 
> >
> > No. I'm saying that, if we want to have a single build process
> > for multiple sphinxdirs, that sounds to be the better way to do it
> > to override sphinx-build limitation of having single source directory.
> >
> > The advantages is that:
> >     - brings more performance, as a single build would be enough;
> >     - cross-references between them will be properly solved.
> >
> > The disadvantages are:
> >     - it would very likely need to create copies (or hard symlinks)
> >       at the build dir, which may reduce performance;
> >     - yet-another-hack;
> >     - increased build complexity.
> >
> > I'm not convinced myself about doing it or not. I didn't like when
> > I had to do that after the media book was split on 3 books. If one thinks
> > that having for loops to build targets is a problem, we need a separate
> > discussion about how to avoid it. Also, this is outside of the scope of
> > this series.
> 
> I honestly don't even understand what you're saying above

Perhaps it is due to the lack of context. I was replying some comments
from Akira where he mentioned about cherry-picking *.tex files after
sphinx build, and do some tricks to build all of them altogether.

My reply to his comments is that, if we're willing to cherry-pick things,
it is better/cleaner/safer to do it at the beginning, before even running
sphinx-build, ensuring no conflicts at the filename mapping.

Yet, analyzing the alternative I proposed, I see both pros and cons - up
to the point that I'm not convinced myself if it is worth doing such
changes upstream or not.

> and how it
> contradicts with what I said about cherry-picking the documentation to
> build.

It doesn't.
 
-- 
Thanks,
Mauro