Re: [PATCH 3/4] Documentation: include the boilerplate for SPHINXDIRS index link

[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:53PM +0200, Jani Nikula wrote:
>> Repeating the index link boilerplate everywhere is tedious. Put it in a
>> subproject-index.rst snippet in a new sphinx-includes directory, and
>> include it.
>> 
>> We'll have to use the relative include, because a) includes are relative
>> to the source file, b) top level include with
>> /sphinx-includes/subproject-index.rst does not work with SPHINXDIRS
>> builds, because the root is the subdirectory in that case.
>> 
>> 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 574896cca198..b9a43ee32a00 100644
>> --- a/Documentation/conf.py
>> +++ b/Documentation/conf.py
>> @@ -38,7 +38,7 @@ else:
>>  doctree = os.path.abspath(".")
>>  
>>  # Exclude of patterns that don't contain directory names, in glob format.
>> -exclude_patterns = []
>> +exclude_patterns = ['sphinx-includes/*']
>
> This doesn't work the way on might expect. The problem also affects
> patch 4.
>
> Basically, when SUBDIRS is used, include and exclude patterns need
> to be dynamically calculated, as, instead of building docs using
>
> Documentation/, the logic builds inside documentation/<directory>
>
> So, instead, you need to do:
>
>     dyn_exclude_patterns.append("sphinx-includes/*")
>
> To ensure that it will pick just the right includes directory.

Sphinx will only look for files within the source directory passed to
sphinx-build. With SPHINXDIRS, the Documentation/ is not it. There's no
need to specifically exclude anything that's outside of the source
directory hierarchy.

The whole dyn_exclude_patterns looks like overkill to me. It should just
look at exclude_patterns, and remove anything that's outside of the
SPHINXDIRS specified, and remove the SPHINXDIRS prefix from the
remaining ones.

In any case, the above exclude_patterns setting will work just fine.


BR,
Jani.


-- 
Jani Nikula, Intel