tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs: conf.py: properly handle include and exclude patterns

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.

It should be noticed that include_patterns was added on
Sphinx 5.1:
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-include_patterns

So, a backward-compatible code is needed when we start
using it for real.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Donald Hunter <donald.hunter@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/429c9c670fe27860f5e4f29aaf72576a4ed52ad1.1750571906.git.mchehab+huawei@kernel.org

authored by

Mauro Carvalho Chehab and committed by
Jonathan Corbet 097fe727 07e04d8e

+63 -4
+63 -4
Documentation/conf.py
··· 17 17 import sphinx 18 18 import shutil 19 19 20 + # Get Sphinx version 21 + major, minor, patch = sphinx.version_info[:3] 22 + 23 + # Include_patterns were added on Sphinx 5.1 24 + if (major < 5) or (major == 5 and minor < 1): 25 + has_include_patterns = False 26 + else: 27 + has_include_patterns = True 28 + # Include patterns that don't contain directory names, in glob format 29 + include_patterns = ['**.rst'] 30 + 31 + # Location of Documentation/ directory 32 + doctree = os.path.abspath('.') 33 + 34 + # Exclude of patterns that don't contain directory names, in glob format. 35 + exclude_patterns = [] 36 + 37 + # List of patterns that contain directory names in glob format. 38 + dyn_include_patterns = [] 39 + dyn_exclude_patterns = ['output'] 40 + 41 + # Properly handle include/exclude patterns 42 + # ---------------------------------------- 43 + 44 + def update_patterns(app, config): 45 + 46 + """ 47 + On Sphinx, all directories are relative to what it is passed as 48 + SOURCEDIR parameter for sphinx-build. Due to that, all patterns 49 + that have directory names on it need to be dynamically set, after 50 + converting them to a relative patch. 51 + 52 + As Sphinx doesn't include any patterns outside SOURCEDIR, we should 53 + exclude relative patterns that start with "../". 54 + """ 55 + 56 + sourcedir = app.srcdir # full path to the source directory 57 + builddir = os.environ.get("BUILDDIR") 58 + 59 + # setup include_patterns dynamically 60 + if has_include_patterns: 61 + for p in dyn_include_patterns: 62 + full = os.path.join(doctree, p) 63 + 64 + rel_path = os.path.relpath(full, start = app.srcdir) 65 + if rel_path.startswith("../"): 66 + continue 67 + 68 + config.include_patterns.append(rel_path) 69 + 70 + # setup exclude_patterns dynamically 71 + for p in dyn_exclude_patterns: 72 + full = os.path.join(doctree, p) 73 + 74 + rel_path = os.path.relpath(full, start = app.srcdir) 75 + if rel_path.startswith("../"): 76 + continue 77 + 78 + config.exclude_patterns.append(rel_path) 79 + 20 80 # helper 21 81 # ------ 22 82 ··· 278 218 #today = '' 279 219 # Else, today_fmt is used as the format for a strftime call. 280 220 #today_fmt = '%B %d, %Y' 281 - 282 - # List of patterns, relative to source directory, that match files and 283 - # directories to ignore when looking for source files. 284 - exclude_patterns = ['output'] 285 221 286 222 # The reST default role (used for this markup: `text`) to use for all 287 223 # documents. ··· 572 516 # the last statement in the conf.py file 573 517 # ------------------------------------------------------------------------------ 574 518 loadConfig(globals()) 519 + 520 + def setup(app): 521 + app.connect('config-inited', update_patterns)