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

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

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.


BR,
Jani.


>
>     Traceback =========
>
>       File "/usr/lib/python3.14/site-packages/sphinx/util/parallel.py", line 137, in _join_one
>         raise SphinxParallelError(*result)
>     sphinx.errors.SphinxParallelError: docutils.utils.SystemMessage: Documentation/userspace-api/media/index.rst:69: (SEVERE/4) Problems with "include" directive path:
>     InputError: [Errno 2] No such file or directory: 'Documentation/userspace-api/sphinx-includes/subproject-index.rst'.
>
> Thanks,
> Mauro

-- 
Jani Nikula, Intel