Re: [PATCH v5 01/15] docs: conf.py: properly handle include and exclude patterns
From: Akira Yokosawa <akiyks@gmail.com>
Date: 2025-06-18 02:42:20
Also in:
linux-doc, linux-kernel-mentees, lkml
Hi Mauro, A comment on compatibility with earlier Sphinx. On Tue, 17 Jun 2025 10:01:58 +0200, Mauro Carvalho Chehab wrote:
quoted hunk ↗ jump to hunk
When one does: make SPHINXDIRS="foo" htmldocs All patterns would be relative to Documentation/foo, which causes the include/exclude patterns like: include_patterns = [ ... f'foo/*.{ext}', ] to break. This is not what it is expected. Address it by adding a logic to dynamically adjust the pattern when SPHINXDIRS is used. That allows adding parsers for other file types. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> --- Documentation/conf.py | 52 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 4 deletions(-)diff --git a/Documentation/conf.py b/Documentation/conf.py index 12de52a2b17e..e887c1b786a4 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py@@ -17,6 +17,54 @@ import os import sphinx import shutil +# Location of Documentation/ directory +doctree = os.path.abspath('.') + +# List of patterns that don't contain directory names, in glob format. +include_patterns = ['**.rst'] +exclude_patterns = [] +
Where "exclude_patterns" has been with us ever since Sphinx 1.0, "include_patterns" was added fairly recently in Sphinx 5.1 [1]. [1]: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-include_patterns So, this breaks earlier Sphinx versions. Also, after applying all of v5 on top of docs-next, I see these new warnings with Sphinx 7.2.6 (of Ubuntu 24.04): /<srcdir>/Documentation/output/ca.h.rst: WARNING: document isn't included in any toctree /<srcdir>/Documentation/output/cec.h.rst: WARNING: document isn't included in any toctree /<srcdir>/Documentation/output/dmx.h.rst: WARNING: document isn't included in any toctree /<srcdir>/Documentation/output/frontend.h.rst: WARNING: document isn't included in any toctree /<srcdir>/Documentation/output/lirc.h.rst: WARNING: document isn't included in any toctree /<srcdir>/Documentation/output/media.h.rst: WARNING: document isn't included in any toctree /<srcdir>/Documentation/output/net.h.rst: WARNING: document isn't included in any toctree /<srcdir>/Documentation/output/videodev2.h.rst: WARNING: document isn't included in any toctree Sphinx 7.3.7 and later are free of them. I have no idea which change in Sphinx 7.3 got rid of them. Now that the parallel build performance regression has be resolved in Sphinx 7.4, I don't think there is much demand for keeping Sphinx versions compatible. These build errors and extra warnings would encourage people to upgrade there Sphinx. So I'm not going to nack this. Of course, getting rid of above warnings with < Sphinx 7.3 would be ideal. Thanks, Akira
+# List of patterns that contain directory names in glob format. +dyn_include_patterns = [] +dyn_exclude_patterns = ['output'] +
[...]