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: <s5gyu27qlfg7frb4v3ssqms6inqammtakwchgl635r3ahooj5n@vhw5tnyti7nd>
Date: Mon, 15 Sep 2025 15:50:39 +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 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.

-

Another alternative to achieve such goal of not needing a loop at Sphinx
to handle multiple books in parallel would be to submit a patch for 
Sphinx to get rid of the current limitation of having a single book
with everything on a single directory. Sphinx has already hacks for it
with "latex_documents", "man_pages", "texinfo_documents" conf.py variables
that are specific for non-html builders.

Still, when such variables are used, a post-sphinx-build logic with a
per-output-file loop is needed.

> I.e. even if we figured out how to
> do intersphinx books, you'd want to grab parts from them and turn them
> into something else?

Either doing it or not, intersphinx is intestesting. 

> Ugh.
> 
> 
> BR,
> Jani.
> 
> 
> -- 
> Jani Nikula, Intel

-- 
Thanks,
Mauro