Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
scripts: test_doc_build.py: make the script smarter
Most of the time, testing the full range of supported Sphinx
version is a waste of time and resources. Instead, the best is
to focus at the versions that are actually shipped by major
distros.
For it to work properly, we need to adjust the requirements for
them to start from first patch for each distro after the
minimal supported one. The requirements were re-adjusted to
avoid build breakages related to version incompatibilities.
Such builds were tested with:
./scripts/test_doc_build.py -m -a "SPHINXOPTS=-j8" "SPHINXDIRS=networking netlink/specs" --full
Change the logic to pick by default only such versions, adding
another parameter to do a comprehensive test.
While here, improve the script documentation to make it easier
to be used.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/a2b9b7775a185766643ea4b82b558de25b61d6c7.1750571906.git.mchehab+huawei@kernel.org
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
791b9b03
0e93f124
+105
-49
+105
-49
scripts/test_doc_build.py
+105
-49
scripts/test_doc_build.py
···
33
33
min_python_bin = PYTHON
34
34
35
35
# Starting from 8.0, Python 3.9 is not supported anymore.
36
-
PYTHON_VER_CHANGES = {(8, 0, 2): PYTHON}
36
+
PYTHON_VER_CHANGES = {(8, 0, 0): PYTHON}
37
+
38
+
DEFAULT_VERSIONS_TO_TEST = [
39
+
(3, 4, 3), # Minimal supported version
40
+
(5, 3, 0), # CentOS Stream 9 / AlmaLinux 9
41
+
(6, 1, 1), # Debian 12
42
+
(7, 2, 1), # openSUSE Leap 15.6
43
+
(7, 2, 6), # Ubuntu 24.04 LTS
44
+
(7, 4, 7), # Ubuntu 24.10
45
+
(7, 3, 0), # openSUSE Tumbleweed
46
+
(8, 1, 3), # Fedora 42
47
+
(8, 2, 3) # Latest version - covers rolling distros
48
+
]
37
49
38
50
# Sphinx versions to be installed and their incremental requirements
39
51
SPHINX_REQUIREMENTS = {
···
76
64
77
65
# Update package dependencies to a more modern base. The goal here
78
66
# is to avoid to many incremental changes for the next entries
79
-
(3, 5, 4): {
67
+
(3, 5, 0): {
80
68
"alabaster": "0.7.13",
81
69
"babel": "2.17.0",
82
70
"certifi": "2025.6.15",
83
71
"idna": "3.10",
84
72
"imagesize": "1.4.1",
85
-
"Jinja2": "3.0.3",
86
-
"MarkupSafe": "2.0",
87
73
"packaging": "25.0",
88
-
"Pygments": "2.19.1",
74
+
"Pygments": "2.8.1",
89
75
"requests": "2.32.4",
90
76
"snowballstemmer": "3.0.1",
91
77
"sphinxcontrib-applehelp": "1.0.4",
92
78
"sphinxcontrib-htmlhelp": "2.0.1",
93
79
"sphinxcontrib-serializinghtml": "1.1.5",
80
+
"urllib3": "2.0.0",
94
81
},
95
82
96
83
# Starting from here, ensure all docutils versions are covered with
97
84
# supported Sphinx versions. Other packages are upgraded only when
98
85
# required by pip
99
-
(4, 0, 3): {
100
-
"docutils": "0.17",
86
+
(4, 0, 0): {
101
87
"PyYAML": "5.1",
102
88
},
103
-
(4, 1, 2): {
89
+
(4, 1, 0): {
90
+
"docutils": "0.17",
91
+
"Pygments": "2.19.1",
92
+
"Jinja2": "3.0.3",
93
+
"MarkupSafe": "2.0",
104
94
},
105
-
(4, 3, 2): {
106
-
},
95
+
(4, 3, 0): {},
107
96
(4, 4, 0): {},
108
-
(4, 5, 0): {},
109
-
(5, 0, 2): {},
110
-
(5, 1, 1): {},
111
-
(5, 2, 3): {
97
+
(4, 5, 0): {
112
98
"docutils": "0.17.1",
99
+
},
100
+
(5, 0, 0): {},
101
+
(5, 1, 0): {},
102
+
(5, 2, 0): {
103
+
"docutils": "0.18",
113
104
"Jinja2": "3.1.2",
114
105
"MarkupSafe": "2.0",
115
106
"PyYAML": "5.3.1",
116
107
},
117
-
(5, 3, 0): {},
118
-
(6, 0, 1): {
119
-
"docutils": "0.18",
120
-
},
121
-
(6, 1, 3): {},
122
-
(6, 2, 1): {
108
+
(5, 3, 0): {
123
109
"docutils": "0.18.1",
110
+
},
111
+
(6, 0, 0): {},
112
+
(6, 1, 0): {},
113
+
(6, 2, 0): {
124
114
"PyYAML": "5.4.1",
125
115
},
126
-
(7, 0, 1): {
127
-
},
128
-
(7, 1, 2): {},
129
-
(7, 2, 3): {
116
+
(7, 0, 0): {},
117
+
(7, 1, 0): {},
118
+
(7, 2, 0): {
130
119
"docutils": "0.19",
131
120
"PyYAML": "6.0.1",
132
121
"sphinxcontrib-serializinghtml": "1.1.9",
133
122
},
134
-
(7, 3, 7): {
123
+
(7, 2, 6): {
135
124
"docutils": "0.20",
125
+
},
126
+
(7, 3, 0): {
136
127
"alabaster": "0.7.14",
137
128
"PyYAML": "6.0.1",
129
+
"tomli": "2.0.1",
138
130
},
139
-
(7, 4, 7): {
140
-
"docutils": "0.21",
131
+
(7, 4, 0): {
132
+
"docutils": "0.20.1",
141
133
"PyYAML": "6.0.1",
142
134
},
143
-
(8, 0, 2): {
144
-
"docutils": "0.21.1",
135
+
(8, 0, 0): {
136
+
"docutils": "0.21",
145
137
},
146
-
(8, 1, 3): {
147
-
"docutils": "0.21.2",
138
+
(8, 1, 0): {
139
+
"docutils": "0.21.1",
148
140
"PyYAML": "6.0.1",
149
141
"sphinxcontrib-applehelp": "1.0.7",
150
142
"sphinxcontrib-devhelp": "1.0.6",
151
143
"sphinxcontrib-htmlhelp": "2.0.6",
152
144
"sphinxcontrib-qthelp": "1.0.6",
153
145
},
154
-
(8, 2, 3): {
146
+
(8, 2, 0): {
147
+
"docutils": "0.21.2",
155
148
"PyYAML": "6.0.1",
156
149
"sphinxcontrib-serializinghtml": "1.1.9",
157
150
},
···
356
339
cur_requirements = {}
357
340
python_bin = min_python_bin
358
341
359
-
for cur_ver, new_reqs in SPHINX_REQUIREMENTS.items():
360
-
cur_requirements.update(new_reqs)
342
+
vers = set(SPHINX_REQUIREMENTS.keys()) | set(args.versions)
343
+
344
+
for cur_ver in sorted(vers):
345
+
if cur_ver in SPHINX_REQUIREMENTS:
346
+
new_reqs = SPHINX_REQUIREMENTS[cur_ver]
347
+
cur_requirements.update(new_reqs)
361
348
362
349
if cur_ver in PYTHON_VER_CHANGES: # pylint: disable=R1715
363
-
364
350
python_bin = PYTHON_VER_CHANGES[cur_ver]
351
+
352
+
if cur_ver not in args.versions:
353
+
continue
365
354
366
355
if args.min_version:
367
356
if cur_ver < args.min_version:
···
396
373
return tuple(map(int, ver_str.split(".")))
397
374
398
375
376
+
DEFAULT_VERS = " - "
377
+
DEFAULT_VERS += "\n - ".join(map(lambda v: f"{v[0]}.{v[1]}.{v[2]}",
378
+
DEFAULT_VERSIONS_TO_TEST))
379
+
380
+
SCRIPT = os.path.relpath(__file__)
381
+
382
+
DESCRIPTION = f"""
383
+
This tool allows creating Python virtual environments for different
384
+
Sphinx versions that are supported by the Linux Kernel build system.
385
+
386
+
Besides creating the virtual environment, it can also test building
387
+
the documentation using "make htmldocs".
388
+
389
+
If called without "--versions" argument, it covers the versions shipped
390
+
on major distros, plus the lowest supported version:
391
+
392
+
{DEFAULT_VERS}
393
+
394
+
A typical usage is to run:
395
+
396
+
{SCRIPT} -m -l sphinx_builds.log
397
+
398
+
This will create one virtual env for the default version set and do a
399
+
full htmldocs build for each version, creating a log file with the
400
+
excecuted commands on it.
401
+
402
+
NOTE: The build time can be very long, specially on old versions. Also, there
403
+
is a known bug with Sphinx version 6.0.x: each subprocess uses a lot of
404
+
memory. That, together with "-jauto" may cause OOM killer to cause
405
+
failures at the doc generation. To minimize the risk, you may use the
406
+
"-a" command line parameter to constrain the built directories and/or
407
+
reduce the number of threads from "-jauto" to, for instance, "-j4":
408
+
409
+
{SCRIPT} -m -V 6.0.1 -a "SPHINXDIRS=process" "SPHINXOPTS='-j4'"
410
+
411
+
"""
412
+
413
+
399
414
async def main():
400
415
"""Main program"""
401
416
402
-
parser = argparse.ArgumentParser(description="Build docs for different sphinx_versions.")
417
+
parser = argparse.ArgumentParser(description=DESCRIPTION,
418
+
formatter_class=argparse.RawDescriptionHelpFormatter)
403
419
404
-
parser.add_argument('-V', '--version', help='Sphinx single version',
420
+
parser.add_argument('-V', '--versions', help='Sphinx versions to test',
421
+
nargs="*", default=DEFAULT_VERSIONS_TO_TEST,
405
422
type=parse_version)
406
423
parser.add_argument('--min-version', "--min", help='Sphinx minimal version',
407
424
type=parse_version)
···
454
391
action='store_true')
455
392
parser.add_argument('-m', '--make',
456
393
help='Make documentation',
394
+
action='store_true')
395
+
parser.add_argument('-f', '--full',
396
+
help='Add all (major,minor,latest_patch) version to the version list',
457
397
action='store_true')
458
398
parser.add_argument('-i', '--wait-input',
459
399
help='Wait for an enter before going to the next version',
···
472
406
if not args.make_args:
473
407
args.make_args = []
474
408
475
-
if args.version:
476
-
if args.min_version or args.max_version:
477
-
sys.exit("Use either --version or --min-version/--max-version")
478
-
else:
479
-
args.min_version = args.version
480
-
args.max_version = args.version
481
-
482
409
sphinx_versions = sorted(list(SPHINX_REQUIREMENTS.keys()))
483
410
484
-
if not args.min_version:
485
-
args.min_version = sphinx_versions[0]
486
-
487
-
if not args.max_version:
488
-
args.max_version = sphinx_versions[-1]
411
+
if args.full:
412
+
args.versions += list(SPHINX_REQUIREMENTS.keys())
489
413
490
414
venv = SphinxVenv()
491
415
await venv.run(args)