torvalds/linux
torvalds/linux
2
0
Fork 0
mirror of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2025-09-04 20:19:47 +08:00
Code

scripts: test_doc_build.py: regroup and rename arguments

Browse Source 
The script now have lots or arguments. Better organize and
name them, for it to be a little bit more intuitive.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/acf5e1db38ca6a713c44ceca9db5cdd7d3079c92.1750571906.git.mchehab+huawei@kernel.org
This commit is contained in:
Mauro Carvalho Chehab 2025-06-22 08:02:41 +02:00 committed by Jonathan Corbet
parent 61aeda1e5c
commit bb4c5c50ae
1 changed files with 61 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
scripts/test_doc_build.py
View File

@ -269,7 +269,7 @@ class SphinxVenv:
ver = ".".join(map(str, cur_ver)) ver = ".".join(map(str, cur_ver))
if not self.first_run and args.wait_input and args.make: if not self.first_run and args.wait_input and args.build:
ret = input("Press Enter to continue or 'a' to abort: ").strip().lower() ret = input("Press Enter to continue or 'a' to abort: ").strip().lower()
if ret == "a": if ret == "a":
print("Aborted.") print("Aborted.")
@ -300,11 +300,11 @@ class SphinxVenv:
result = await cmd.run([pip, "freeze"], verbose=False, check=True) result = await cmd.run([pip, "freeze"], verbose=False, check=True)
# Pip install succeeded. Write requirements file # Pip install succeeded. Write requirements file
if args.write: if args.req_file:
with open(req_file, "w", encoding="utf-8") as fp: with open(req_file, "w", encoding="utf-8") as fp:
fp.write(result.stdout) fp.write(result.stdout)
if args.make: if args.build:
start_time = time.time() start_time = time.time()
# Prepare a venv environment # Prepare a venv environment
@ -317,7 +317,16 @@ class SphinxVenv:
# Test doc build # Test doc build
await cmd.run(["make", "cleandocs"], env=env, check=True) await cmd.run(["make", "cleandocs"], env=env, check=True)
make = ["make"] + args.make_args + ["htmldocs"] make = ["make"]
if args.output:
sphinx_build = os.path.realpath(f"{bin_dir}/sphinx-build")
make += [f"O={args.output}", f"SPHINXBUILD={sphinx_build}"]
if args.make_args:
make += args.make_args
make += args.targets
if args.verbose: if args.verbose:
cmd.log(f". {bin_dir}/activate", verbose=True) cmd.log(f". {bin_dir}/activate", verbose=True)
@ -380,7 +389,7 @@ class SphinxVenv:
await self._handle_version(args, fp, cur_ver, cur_requirements, await self._handle_version(args, fp, cur_ver, cur_requirements,
python_bin) python_bin)
if args.make: if args.build:
cmd = AsyncCommands(fp) cmd = AsyncCommands(fp)
cmd.log("\nSummary:", verbose=True) cmd.log("\nSummary:", verbose=True)
for ver, elapsed_time in sorted(self.built_time.items()): for ver, elapsed_time in sorted(self.built_time.items()):
@ -407,7 +416,7 @@ This tool allows creating Python virtual environments for different
Sphinx versions that are supported by the Linux Kernel build system. Sphinx versions that are supported by the Linux Kernel build system.
Besides creating the virtual environment, it can also test building Besides creating the virtual environment, it can also test building
the documentation using "make htmldocs". the documentation using "make htmldocs" (and/or other doc targets).
If called without "--versions" argument, it covers the versions shipped If called without "--versions" argument, it covers the versions shipped
on major distros, plus the lowest supported version: on major distros, plus the lowest supported version:
@ -418,8 +427,8 @@ A typical usage is to run:
{SCRIPT} -m -l sphinx_builds.log {SCRIPT} -m -l sphinx_builds.log
This will create one virtual env for the default version set and do a This will create one virtual env for the default version set and run
full htmldocs build for each version, creating a log file with the "make htmldocs" for each version, creating a log file with the
excecuted commands on it. excecuted commands on it.
NOTE: The build time can be very long, specially on old versions. Also, there NOTE: The build time can be very long, specially on old versions. Also, there
@ -433,6 +442,15 @@ reduce the number of threads from "-jauto" to, for instance, "-j4":
""" """
MAKE_TARGETS = [
"htmldocs",
"texinfodocs",
"infodocs",
"latexdocs",
"pdfdocs",
"epubdocs",
"xmldocs",
]
async def main(): async def main():
"""Main program""" """Main program"""
@ -440,32 +458,41 @@ async def main():
parser = argparse.ArgumentParser(description=DESCRIPTION, parser = argparse.ArgumentParser(description=DESCRIPTION,
formatter_class=argparse.RawDescriptionHelpFormatter) formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument('-V', '--versions', help='Sphinx versions to test', ver_group = parser.add_argument_group("Version range options")
nargs="*", default=DEFAULT_VERSIONS_TO_TEST,
type=parse_version) ver_group.add_argument('-V', '--versions', nargs="*",
parser.add_argument('--min-version', "--min", help='Sphinx minimal version', default=DEFAULT_VERSIONS_TO_TEST,type=parse_version,
type=parse_version) help='Sphinx versions to test')
parser.add_argument('--max-version', "--max", help='Sphinx maximum version', ver_group.add_argument('--min-version', "--min", type=parse_version,
type=parse_version) help='Sphinx minimal version')
parser.add_argument('-a', '--make_args', ver_group.add_argument('--max-version', "--max", type=parse_version,
help='extra arguments for make htmldocs, like SPHINXDIRS=netlink/specs', help='Sphinx maximum version')
nargs="*") ver_group.add_argument('-f', '--full', action='store_true',
parser.add_argument('-w', '--write', help='write a requirements.txt file', help='Add all Sphinx (major,minor) supported versions to the version range')
action='store_true')
parser.add_argument('-m', '--make', build_group = parser.add_argument_group("Build options")
help='Make documentation',
action='store_true') build_group.add_argument('-b', '--build', action='store_true',
parser.add_argument('-f', '--full', help='Build documentation')
help='Add all (major,minor,latest_patch) version to the version list', build_group.add_argument('-a', '--make-args', nargs="*",
action='store_true') help='extra arguments for make, like SPHINXDIRS=netlink/specs',
parser.add_argument('-i', '--wait-input', )
help='Wait for an enter before going to the next version', build_group.add_argument('-t', '--targets', nargs="+", choices=MAKE_TARGETS,
action='store_true') default=[MAKE_TARGETS[0]],
parser.add_argument('-v', '--verbose', help="make build targets. Default: htmldocs.")
help='Verbose all commands', build_group.add_argument("-o", '--output',
action='store_true') help="output directory for the make O=OUTPUT")
parser.add_argument('-l', '--log',
help='Log command output on a file') other_group = parser.add_argument_group("Other options")
other_group.add_argument('-r', '--req-file', action='store_true',
help='write a requirements.txt file')
other_group.add_argument('-l', '--log',
help='Log command output on a file')
other_group.add_argument('-v', '--verbose', action='store_true',
help='Verbose all commands')
other_group.add_argument('-i', '--wait-input', action='store_true',
help='Wait for an enter before going to the next version')
args = parser.parse_args() args = parser.parse_args()