Re: [PATCH v6 10/21] tools/docs: sphinx-build-wrapper: add a wrapper for sphinx-build

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Thu, 18 Sep 2025 08:43:19 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> Hi Jon,
> 
> Jonathan Corbet wrote:
> > Akira Yokosawa <akiyks@gmail.com> writes:
> >   
> >> Wait!  In the cover-letter, you said:
> >>
> >>     It should be noticed that it is out of the scope of this series
> >>     to change the implementation. Surely the process can be improved,
> >>     but first let's consolidate and document everything on a single
> >>     place.
> >>
> >> Removing current restriction on SPHINXDIRS does look inconsistent with
> >> your own words to me.
> >>
> >> So, I guess I have to NAK 06/21 as well.  
> > 
> > Is there an actual problem with this change that we need to know about?
> > I am not quite understanding the objection here.  
> 
> As Mauro has pointed out, and as I could not apply v6 series, I failed
> to look at the whole patch.
> 
> My knee jerk reaction came from the fact that, for example,
> 
>     make SPHINXDIRS=translations/zh_CN pdfdocs
> 
> won't build.  This is because I didn't know such a sub-directory is
> allowed (despite what "make dochelp" says) in SPHINXDIRS.

The build system does support it, provided that the directory has
an index.rst file (not all subdirs have)...

> 
> At the time I made "improvements in CJK font configs", I embedded
> hacky ".. raw:: latex     \kerneldocCJKoff" and others in:
> 
>      Documentations/index.rst
>                    /*/index.rst

... and that ".. raw:: " entries don't depend on previous .rst files.

> , assuming all of those latex macros would appear in translations.tex
> in the right order.
> 
> I admit it was not ideal, but I could not, and still can not, come up
> with a more robust approach.

For LaTeX build, ".. raw:: " entries can be unavoidable, but you could
place it either:

- at conf.py if they're global;
- on each rst file (that's what we do on media);
- in the case of translations, for the languages that require CJK.

Grepping it:

	$ git grep kerneldocCJK Documentation/translations/
	Documentation/translations/index.rst:   \kerneldocCJKoff
	Documentation/translations/it_IT/index.rst:     \kerneldocCJKoff
	Documentation/translations/ja_JP/index.rst:     \kerneldocCJKon
	Documentation/translations/ko_KR/index.rst:     \kerneldocCJKon
	Documentation/translations/ko_KR/process/howto.rst:     \kerneldocCJKoff
	Documentation/translations/ko_KR/process/howto.rst:     \kerneldocCJKon
	Documentation/translations/sp_SP/index.rst:     \kerneldocCJKoff
	Documentation/translations/zh_CN/index.rst:     \kerneldocCJKon
	Documentation/translations/zh_TW/index.rst:     \kerneldocCJKon

Indeed it assumes that translations/index.rst will be the last one,
as it is needed to disable \kerneldocCJKoff.

What I would do is move \kerneldocCJK to each book, e.g.:

   zh_CN/index:	will have a \kerneldocCJK{on/off} pair;
   zh_TW/index:	will have a \kerneldocCJK{on/off} pair;
   it_IT/index: won't use it, as it doesn't need CJK fonts;
   ko_KR/index:	will have a \kerneldocCJK{on/off} pair;
   ja_JP/index:	will have a \kerneldocCJK{on/off} pair;
   sp_SP/index:	will have a \kerneldocCJK{on/off} pair;
   process/index: won't use it, as everything there is in English;

This would likely allow creating each translation on separate books
like:

	make SPHINXDIRS="translations/zh_CN translations/ko_KR ..." pdfdocs

Heh, the audience for each language is completely different, so
merging them altogether is actually weird. This doesn't matter 
much for html output, but for all other outputs, ideally each
translation should be a separate book.

With the current Makefile-hacky-based-approach, supporting separate
build books would be very complex, but with a wrapper containing the
entire building logic, it doesn't sound hard to add support in the
future to build translations as separate entities.=

Heh, when we added Sphinx support, we have a single Documentation
directory, but now we have multiple ones:

	$ find . -name Documentation
	./tools/bpf/bpftool/Documentation
	./tools/perf/Documentation
	./tools/memory-model/Documentation
	./tools/lib/perf/Documentation
	./tools/objtool/Documentation
	./tools/build/Documentation
	./Documentation
	./drivers/staging/most/Documentation
	./drivers/staging/greybus/Documentation
	./drivers/staging/iio/Documentation

Considering that, and considering the some of the above books can
be in ReST format, it doesn't sound too complex to add a --docdir
parameter at sphinx-build-wrapper and do things like:

	./tools/docs/sphinx-build-wrapper --docdir Documentation/translations/zh_CN htmldocs
	./tools/docs/sphinx-build-wrapper --docdir Documentation/translations/zh_TW epubdocs
	./tools/docs/sphinx-build-wrapper --docdir ./tools/bpf/bpftool/Documentation mandocs

On such scenario, we likely need intersphinx, as translation books contain lots of
references pointing to the English one.


Thanks,
Mauro