fix: overhaul docs build process (#103)

cofin · web-flow · commit b2b18cd1040b · 2025-10-07T22:38:03.000-05:00
Fixes the documentation build failure caused by attempting to checkout a non-existent `gh-pages` branch.

This PR modernizes the documentation build and deployment workflow to use GitHub's current best practices for GitHub Pages deployment (2025).
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -1,16 +1,15 @@
 name: Documentation Build
 
 on:
-  release:
-    types: [published]
   push:
     branches:
       - main
 
+permissions:
+  contents: read
+
 jobs:
-  docs:
-    permissions:
-      contents: write
+  build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -27,23 +26,25 @@ jobs:
       - name: Build documentation
         run: uv run python tools/build_docs.py docs-build
 
-      - name: Package documentation artifact
-        run: tar -czvf docs-build.tar.gz docs-build
-
-      - name: Upload Release Asset
-        if: github.event_name == 'release'
-        uses: actions/upload-release-asset@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v4
         with:
-          upload_url: ${{ github.event.release.upload_url }}
-          asset_path: ./docs-build.tar.gz
-          asset_name: docs-build-${{ github.ref_name }}.tar.gz
-          asset_content_type: application/gzip
-
-      - name: Upload 'latest' docs artifact
-        if: github.event_name == 'push'
-        uses: actions/upload-artifact@v4
-        with:
-          name: latest-docs
-          path: docs-build.tar.gz
+          path: docs-build
+
+  deploy:
+    needs: build
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -65,3 +65,4 @@ CRUSH.md
 *.md
 !./README.md
 !./CONTRIBUTING.md
+docs-build
diff --git a/tools/build_docs.py b/tools/build_docs.py
@@ -1,92 +1,34 @@
 from __future__ import annotations
 
 import argparse
-import importlib.metadata
-import json
-import os
 import shutil
 import subprocess
-from collections.abc import Generator
-from contextlib import contextmanager
 from pathlib import Path
-from typing import TYPE_CHECKING, TypedDict, cast
-
-if TYPE_CHECKING:
-    from collections.abc import Generator
-
-REDIRECT_TEMPLATE = """
-<!DOCTYPE HTML>
-<html lang="en-US">
-    <head>
-        <title>Page Redirection</title>
-        <meta charset="UTF-8">
-        <meta http-equiv="refresh" content="0; url={target}">
-        <script type="text/javascript">window.location.href = "{target}"</script>
-    </head>
-    <body>
-        You are being redirected. If this does not work, click <a href='{target}'>this link</a>
-    </body>
-</html>
-"""
 
 parser = argparse.ArgumentParser()
-parser.add_argument("--version", required=False)
 parser.add_argument("output")
 
 
-class VersionSpec(TypedDict):
-    versions: list[str]
-    latest: str
-
-
-@contextmanager
-def checkout(branch: str) -> Generator[None]:
-    subprocess.run(["git", "checkout", branch], check=True)  # noqa: S607
-    yield
-    subprocess.run(["git", "checkout", "-"], check=True)  # noqa: S607
-
-
-def load_version_spec() -> VersionSpec:
-    versions_file = Path("docs/_static/versions.json")
-    if versions_file.exists():
-        return cast("VersionSpec", json.loads(versions_file.read_text()))
-    return {"versions": [], "latest": ""}
-
-
-def build(output_dir: str, version: str | None) -> None:
-    if version is None:
-        version = importlib.metadata.version("sqlspec").rsplit(".")[0]
-    else:
-        os.environ["_SQLSPEC_DOCS_BUILD_VERSION"] = version
-
+def build(output_dir: str) -> None:
     subprocess.run(["make", "docs"], check=True)  # noqa: S607
 
-    Path(output_dir).mkdir()
-    Path(output_dir).joinpath(".nojekyll").touch(exist_ok=True)
-
-    version_spec = load_version_spec()
-    is_latest = version == version_spec["latest"]
-
     docs_src_path = Path("docs/_build/html")
+    output_path = Path(output_dir)
 
-    Path(output_dir).joinpath("index.html").write_text(REDIRECT_TEMPLATE.format(target="latest"))
-
-    if is_latest:
-        shutil.copytree(docs_src_path, Path(output_dir) / "latest", dirs_exist_ok=True)
-    shutil.copytree(docs_src_path, Path(output_dir) / version, dirs_exist_ok=True)
+    output_path.mkdir(parents=True, exist_ok=True)
+    output_path.joinpath(".nojekyll").touch(exist_ok=True)
 
-    # copy existing versions into our output dir to preserve them when cleaning the branch
-    with checkout("gh-pages"):
-        for other_version in [*version_spec["versions"], "latest"]:
-            other_version_path = Path(other_version)
-            other_version_target_path = Path(output_dir) / other_version
-            if other_version_path.exists() and not other_version_target_path.exists():
-                shutil.copytree(other_version_path, other_version_target_path)
+    for item in docs_src_path.iterdir():
+        dest = output_path / item.name
+        if item.is_dir():
+            shutil.copytree(item, dest, dirs_exist_ok=True)
+        else:
+            shutil.copy2(item, dest)
 
 
 def main() -> None:
     args = parser.parse_args()
-    build(output_dir=args.output, version=args.version)
+    build(output_dir=args.output)
 
 
 if __name__ == "__main__":
