Allow passing multiple branches to build via CLI (#235)

Author: hugovk

.coveragerc

@@ -0,0 +1,7 @@
+# .coveragerc to control coverage.py
+
+[report]
+# Regexes for lines to exclude from consideration
+exclude_also =
+    # Don't complain if non-runnable code isn't run:
+    if __name__ == .__main__.:

.github/workflows/test.yml

@@ -33,3 +33,10 @@ jobs:
       - name: Tox tests
         run: |
           uvx --with tox-uv tox -e py
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v5
+        with:
+          flags: ${{ matrix.os }}
+          name: ${{ matrix.os }} Python ${{ matrix.python-version }}
+          token: ${{ secrets.CODECOV_ORG_TOKEN }}

README.md

@@ -1,3 +1,8 @@
+# docsbuild-scripts
+
+[![GitHub Actions status](https://github.com/python/docsbuild-scripts/actions/workflows/test.yml/badge.svg)](https://github.com/python/docsbuild-scripts/actions/workflows/test.yml)
+[![Codecov](https://codecov.io/gh/python/docsbuild-scripts/branch/main/graph/badge.svg)](https://codecov.io/gh/python/docsbuild-scripts)
+
 This repository contains scripts for automatically building the Python
 documentation on [docs.python.org](https://docs.python.org).
 
@@ -12,7 +17,7 @@ python3 ./build_docs.py --quick --build-root ./build_root --www-root ./www --log
 ```
 
 If you don't need to build all translations of all branches, add
-`--language en --branch main`.
+`--languages en --branches main`.
 
 
 ## Check current version

build_docs.py

@@ -87,16 +87,17 @@ def from_json(cls, data) -> Versions:
         )
         return cls(versions)
 
-    def filter(self, branch: str = "") -> Sequence[Version]:
+    def filter(self, branches: Sequence[str] = ()) -> Sequence[Version]:
         """Filter the given versions.
 
-        If *branch* is given, only *versions* matching *branch* are returned.
+        If *branches* is given, only *versions* matching *branches* are returned.
 
         Else all live versions are returned (this means no EOL and no
         security-fixes branches).
         """
-        if branch:
-            return [v for v in self if branch in (v.name, v.branch_or_tag)]
+        if branches:
+            branches = frozenset(branches)
+            return [v for v in self if {v.name, v.branch_or_tag} & branches]
         return [v for v in self if v.status not in {"EOL", "security-fixes"}]
 
     @property
@@ -936,9 +937,10 @@ def parse_args():
     )
     parser.add_argument(
         "-b",
-        "--branch",
+        "--branches",
+        nargs="*",
         metavar="3.12",
-        help="Version to build (defaults to all maintained branches).",
+        help="Versions to build (defaults to all maintained branches).",
     )
     parser.add_argument(
         "-r",
@@ -972,7 +974,6 @@ def parse_args():
     )
     parser.add_argument(
         "--languages",
-        "--language",
         nargs="*",
         help="Language translation, as a PEP 545 language tag like"
         " 'fr' or 'pt-br'. "
@@ -1046,10 +1047,10 @@ def build_docs(args: argparse.Namespace) -> bool:
     # This runs languages in config.toml order and versions newest first.
     todo = [
         (version, language)
-        for version in versions.filter(args.branch)
+        for version in versions.filter(args.branches)
         for language in reversed(languages.filter(args.languages))
     ]
-    del args.branch
+    del args.branches
     del args.languages
 
     build_succeeded = set()

tests/test_build_docs_versions.py

@@ -0,0 +1,62 @@
+from build_docs import Versions, Version
+
+
+def test_filter_default() -> None:
+    # Arrange
+    versions = Versions([
+        Version("3.14", status="feature"),
+        Version("3.13", status="bugfix"),
+        Version("3.12", status="bugfix"),
+        Version("3.11", status="security"),
+        Version("3.10", status="security"),
+        Version("3.9", status="security"),
+    ])
+
+    # Act
+    filtered = versions.filter()
+
+    # Assert
+    assert filtered == [
+        Version("3.14", status="feature"),
+        Version("3.13", status="bugfix"),
+        Version("3.12", status="bugfix"),
+    ]
+
+
+def test_filter_one() -> None:
+    # Arrange
+    versions = Versions([
+        Version("3.14", status="feature"),
+        Version("3.13", status="bugfix"),
+        Version("3.12", status="bugfix"),
+        Version("3.11", status="security"),
+        Version("3.10", status="security"),
+        Version("3.9", status="security"),
+    ])
+
+    # Act
+    filtered = versions.filter(["3.13"])
+
+    # Assert
+    assert filtered == [Version("3.13", status="security")]
+
+
+def test_filter_multiple() -> None:
+    # Arrange
+    versions = Versions([
+        Version("3.14", status="feature"),
+        Version("3.13", status="bugfix"),
+        Version("3.12", status="bugfix"),
+        Version("3.11", status="security"),
+        Version("3.10", status="security"),
+        Version("3.9", status="security"),
+    ])
+
+    # Act
+    filtered = versions.filter(["3.13", "3.14"])
+
+    # Assert
+    assert filtered == [
+        Version("3.14", status="feature"),
+        Version("3.13", status="security"),
+    ]

tox.ini

@@ -12,8 +12,19 @@ skip_install = true
 deps =
     -r requirements.txt
     pytest
+    pytest-cov
+pass_env =
+    FORCE_COLOR
+set_env =
+    COVERAGE_CORE = sysmon
 commands =
-    {envpython} -m pytest {posargs}
+    {envpython} -m pytest \
+      --cov . \
+      --cov tests \
+      --cov-report html \
+      --cov-report term \
+      --cov-report xml \
+      {posargs}
 
 [testenv:lint]
 skip_install = true