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

[Jani Nikula <jani.nikula@linux.intel.com>]

On Mon, 15 Sep 2025, Mauro Carvalho Chehab <mchehab+huawei@kernel.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@kernel.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, and how it
contradicts with what I said about cherry-picking the documentation to
build.

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

-- 
Jani Nikula, Intel