From 596bfaddaad4fc1f4463795ffefae472a89a7132 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 25 Sep 2024 07:55:11 +0100 Subject: [PATCH 1/3] Add ``--select-output`` --- .gitignore | 2 ++ build_docs.py | 85 +++++++++++++++++++++++++-------------------------- 2 files changed, 43 insertions(+), 44 deletions(-) diff --git a/.gitignore b/.gitignore index aaefb08..c257236 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,8 @@ /www/ # temporary lock file created while building the docs build_docs.lock +build_docs_archives.lock +build_docs_html.lock # Created by https://www.gitignore.io/api/python diff --git a/build_docs.py b/build_docs.py index 255f45d..71b9b0f 100755 --- a/build_docs.py +++ b/build_docs.py @@ -44,7 +44,7 @@ from string import Template from textwrap import indent from time import perf_counter, sleep -from typing import Iterable +from typing import Iterable, Literal from urllib.parse import urljoin import jinja2 @@ -487,11 +487,16 @@ def parse_args(): parser = ArgumentParser( description="Runs a build of the Python docs for various branches." ) + parser.add_argument( + "--select-output", + choices=("no-html", "only-html"), + help="Choose what outputs to build.", + ) parser.add_argument( "-q", "--quick", action="store_true", - help="Make HTML files only (Makefile rules suffixed with -html).", + help="Run a quick build (only HTML files).", ) parser.add_argument( "-b", @@ -589,6 +594,7 @@ class DocBuilder: cpython_repo: Repository build_root: Path www_root: Path + select_output: Literal["no-html", "only-html"] | None quick: bool group: str log_directory: Path @@ -596,16 +602,10 @@ class DocBuilder: theme: Path @property - def full_build(self): - """Tell if a full build is needed. - - A full build is slow; it builds pdf, txt, epub, texinfo, and - archives everything. - - A partial build only builds HTML and does not archive, it's - fast. - """ - return not self.quick and not self.language.html_only + def html_only(self): + return ( + self.select_output == "only-html" or self.quick or self.language.html_only + ) def run(self, http: urllib3.PoolManager) -> bool: """Build and publish a Python doc, for a language, and a version.""" @@ -698,15 +698,13 @@ def build(self): if self.version.status == "EOL": sphinxopts.append("-D html_context.outdated=1") - maketarget = ( - "autobuild-" - + ( - "dev" - if self.version.status in ("in development", "pre-release") - else "stable" - ) - + ("" if self.full_build else "-html") - ) + + if self.version.status in ("in development", "pre-release"): + maketarget = "autobuild-dev" + else: + maketarget = "autobuild-stable" + if self.html_only: + maketarget += "-html" logging.info("Running make %s", maketarget) python = self.venv / "bin" / "python" sphinxbuild = self.venv / "bin" / "sphinx-build" @@ -815,28 +813,18 @@ def copy_build_to_webroot(self, http: urllib3.PoolManager) -> None: ";", ] ) - if self.full_build: - run( - [ - "rsync", - "-a", - "--delete-delay", - "--filter", - "P archives/", - str(self.checkout / "Doc" / "build" / "html") + "/", - target, - ] - ) - else: - run( - [ - "rsync", - "-a", - str(self.checkout / "Doc" / "build" / "html") + "/", - target, - ] - ) - if self.full_build: + run( + [ + "rsync", + "-a", + "--delete-delay", + "--filter", + "P archives/", + str(self.checkout / "Doc" / "build" / "html") + "/", + target, + ] + ) + if not self.quick: logging.debug("Copying dist files.") run( [ @@ -1201,8 +1189,17 @@ def main(): args = parse_args() setup_logging(args.log_directory) + if args.select_output is None: + build_docs_with_lock(args, "build_docs.lock") + elif args.select_output == "no-html": + build_docs_with_lock(args, "build_docs_archives.lock") + elif args.select_output == "only-html": + build_docs_with_lock(args, "build_docs_html.lock") + + +def build_docs_with_lock(args, lockfile_name): try: - lock = zc.lockfile.LockFile(HERE / "build_docs.lock") + lock = zc.lockfile.LockFile(HERE / lockfile_name) except zc.lockfile.LockError: logging.info("Another builder is running... dying...") return EX_FAILURE From 9aaa47014baf32865632e86d961d274f5b9b6c3a Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Thu, 26 Sep 2024 17:51:57 +0100 Subject: [PATCH 2/3] Use unique checkouts --- build_docs.py | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/build_docs.py b/build_docs.py index 71b9b0f..0ed5017 100755 --- a/build_docs.py +++ b/build_docs.py @@ -630,7 +630,7 @@ def run(self, http: urllib3.PoolManager) -> bool: @property def checkout(self) -> Path: """Path to CPython git clone.""" - return self.build_root / "cpython" + return self.build_root / _checkout_name(self.select_output) def clone_translation(self): self.translation_repo.update() @@ -1129,7 +1129,8 @@ def build_docs(args) -> bool: del args.languages all_built_successfully = True cpython_repo = Repository( - "https://github.com/python/cpython.git", args.build_root / "cpython" + "https://github.com/python/cpython.git", + args.build_root / _checkout_name(args.select_output), ) while todo: version, language = todo.pop() @@ -1184,6 +1185,12 @@ def build_docs(args) -> bool: return all_built_successfully +def _checkout_name(select_output: str | None) -> str: + if select_output is not None: + return f"cpython-{select_output}" + return "cpython" + + def main(): """Script entry point.""" args = parse_args() From 5f25dcdf178bc682a1a94e0957f64c974acd1009 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Thu, 26 Sep 2024 17:52:47 +0100 Subject: [PATCH 3/3] hints for build_docs_with_lock --- build_docs.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/build_docs.py b/build_docs.py index 0ed5017..b977ee7 100755 --- a/build_docs.py +++ b/build_docs.py @@ -22,7 +22,7 @@ from __future__ import annotations -from argparse import ArgumentParser +from argparse import ArgumentParser, Namespace from collections.abc import Sequence from contextlib import suppress, contextmanager from dataclasses import dataclass @@ -1204,7 +1204,7 @@ def main(): build_docs_with_lock(args, "build_docs_html.lock") -def build_docs_with_lock(args, lockfile_name): +def build_docs_with_lock(args: Namespace, lockfile_name: str) -> int: try: lock = zc.lockfile.LockFile(HERE / lockfile_name) except zc.lockfile.LockError: