Add --select-output (#199)

Author: AA-Turner

.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

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
@@ -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,23 +594,18 @@ 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
     skip_cache_invalidation: bool
     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."""
@@ -635,7 +635,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()
@@ -703,15 +703,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"
@@ -820,28 +818,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(
                 [
@@ -1153,7 +1141,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()
@@ -1208,13 +1197,28 @@ 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()
     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: Namespace, lockfile_name: str) -> int:
     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