Re: [PATCH 4/4] Documentation: use a source-read extension to include the index boilerplate

[Randy Dunlap <rdunlap@infradead.org>]

On 11/13/25 12:12 AM, Jani Nikula wrote:
> On Wed, 12 Nov 2025, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
>> On Wed, Nov 12, 2025 at 01:56:54PM +0200, Jani Nikula wrote:
>>> Reduce boilerplate all over the place by adding a small ad hoc extension
>>> in conf.py that adds the ../sphinx-includes/subproject-index.rst include
>>> to all SPHINXDIRS builds.
>>>
>>> Note that the docname is just 'index', because the SPHINXDIRS builds
>>> happen in the subdirectories.
>>>
>>> Cc: Randy Dunlap <rdunlap@infradead.org>
>>> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>> Cc: Jonathan Corbet <corbet@lwn.net>
>>> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
>>
>>> diff --git a/Documentation/conf.py b/Documentation/conf.py
>>> index b9a43ee32a00..cb0936a71d52 100644
>>> --- a/Documentation/conf.py
>>> +++ b/Documentation/conf.py
>>> @@ -589,8 +589,14 @@ kerneldoc_srctree = ".."
>>>  # ------------------------------------------------------------------------------
>>>  loadConfig(globals())
>>>  
>>> +# Add index link to SPHINXDIRS builds
>>> +def add_subproject_index(app, docname, source):
>>> +    if app.builder.tags.has('subproject') and app.builder.tags.has('html'):
>>> +        if docname == 'index':
>>> +            source[0] += '\n.. include:: ../sphinx-includes/subproject-index.rst\n'
>>
>> The relative path there breaks SPINXDIRS, when it is pointing to use a sub-sub-dir
>> like:
>>
>>     $ make SPHINXDIRS=userspace-api/media htmldocs
> 
> Ugh, I looked at 'make help' for the "valid values for SPHINXDIRS",
> which only lists the top level directories. Patch 1 is also based on
> this.
> 
> What a surprise, the documentation for documentation is useless.

Yeah, I only found out recently that subdirs can be specified there.

-- 
~Randy