Re: [PATCH 0/4] Documentation: clean up subproject index boilerplate

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

On Thu, 13 Nov 2025, Jonathan Corbet <corbet@lwn.net> wrote:
> Jani Nikula <jani.nikula@intel.com> writes:
>
>> Only very lightly tested.
>>
>> Jani Nikula (4):
>>   Documentation: remove subproject index links deep in the structure
>>   Documentation: streamline subproject index link in translations
>>   Documentation: include the boilerplate for SPHINXDIRS index link
>>   Documentation: use a source-read extension to include the index
>>     boilerplate
>
> That bit of repeated gunk has been on my list to look at for a while,
> thanks for digging into it.  Looking forward to the second version.

As I said elsewhere, I didn't realize you could use SPHINXDIRS deeper
than the top level. The implementation is slightly problematic for
translations/. I don't suppose you want to have English "Indices"
heading when using, say, SPHINXDIRS=translations/it_IT/doc-guide?

I guess the alternatives are:

1) Keep having the index links manually in translations/, and don't add
   the template for files there.

2) Accept English "Indices" as a tradeoff.

3) Come up with a system of having multiple language templates for the
   indices, and use them automatically under translations/.

We could also do 2) first and expand to 3) later.

BR,
Jani.



-- 
Jani Nikula, Intel