On Mon, Sep 15, 2025 at 03:54:26PM +0300, Jani Nikula wrote:

On Mon, 15 Sep 2025, Mauro Carvalho Chehab [off-list ref] wrote:

quoted

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