Merge pull request #10 from Arcadia-Science/kcc/add-build-workflow

Add a build workflow

Author: keithchev

.github/workflows/build.yml

@@ -0,0 +1,80 @@
+on:
+  # Run the workflow when new tags are created.
+  push:
+    tags:
+      - v*
+  # Allow the workflow to be triggered manually.
+  workflow_dispatch:
+
+name: Build
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      PUBLISH_BRANCH: publish
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+
+      - name: Create a name for the build branch
+        run: |
+          git checkout main
+          echo "BUILD_BRANCH=build-$(git rev-parse --short HEAD)" >> $GITHUB_ENV
+
+      # Reset the `publish` branch to point to `main`, because we use the `publish` branch
+      # only to store the build artifacts, not for version control.
+      - name: Reset the publish branch
+        run: |
+          git checkout -b $PUBLISH_BRANCH || true
+          git checkout $PUBLISH_BRANCH
+          git reset --hard origin/main
+          git push --force origin $PUBLISH_BRANCH
+          git checkout main
+
+      # Delete the build branch if it already exists,
+      # as the `peter-evans/create-pull-request` action used below will update the branch
+      # if it exists, which we don't want.
+      # Note: deleting the build branch will also close the corresponding PR, if it exists.
+      - name: Delete the build branch
+        run: |
+          git branch -D $BUILD_BRANCH || true
+          git push --force --delete origin $BUILD_BRANCH || true
+
+      - name: Build the publication
+        run: |
+          git checkout main
+          uv run --no-project _build.py
+
+      # Open a PR to merge the build artifacts into the `publish` branch.
+      # Note: this action automatically creates the build branch and commits all unstaged changes to it.
+      - name: Open PR
+        uses: peter-evans/create-pull-request@v7
+        env:
+          PR_BODY: |
+            This PR creates a new version of the public Quarto publication. It was automatically created by the `build.yml` workflow.
+
+            To preview this version of the publication, check out this PR branch locally and run `quarto preview`.
+
+            To publish this version of the publication, merge this PR into the `publish` branch.
+        with:
+          # `base` is the target branch for the PR.
+          base: ${{ env.PUBLISH_BRANCH }}
+          # `branch` is the source branch for the PR.
+          branch: ${{ env.BUILD_BRANCH }}
+          commit-message: "Update the public Quarto publication"
+          title: "[Publication] Update the public Quarto publication"
+          body: ${{ env.PR_BODY }}

.github/workflows/publish.yml

@@ -1,6 +1,6 @@
-# This workflow is taken from
-# https://quarto.org/docs/publishing/github-pages.html#github-action, which
-# contains other useful information.
+# This workflow is derived from an example workflow in the Quarto docs here:
+# https://quarto.org/docs/publishing/github-pages.html#github-action.
+
 on:
   workflow_dispatch:
   push:
@@ -9,13 +9,35 @@ on:
 name: Quarto Publish
 
 jobs:
-  build-deploy:
+  publish:
     runs-on: ubuntu-latest
     permissions:
       contents: write
     steps:
       - name: Check out repository
         uses: actions/checkout@v4
+        with:
+          # Ensure that the `publish` branch is checked out.
+          ref: publish
+
+      # This is needed to create the `gh-pages` branch.
+      - name: Set up Git user
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      # The `quarto-actions/publish` action does not create the `gh-pages` branch,
+      # so we need to create it manually here (if it does not exist).
+      - name: Create the `gh-pages` branch if it does not exist
+        run: |
+          git fetch origin
+          if ! git show-ref --verify --quiet refs/remotes/origin/gh-pages; then
+            git checkout --orphan gh-pages
+            git rm -rf --quiet .
+            git commit --allow-empty -m "Initializing gh-pages branch"
+            git push origin gh-pages
+            git checkout publish
+          fi
 
       - name: Set up Quarto
         uses: quarto-dev/quarto-actions/setup@v2

Makefile

@@ -29,7 +29,3 @@ execute:
 .PHONY: preview
 preview:
 	quarto preview
-
-.PHONY: bump-version
-bump-version:
-	python _bump_version.py

_build.py

@@ -0,0 +1,168 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#   "pyyaml>=6.0.2",
+# ]
+# ///
+
+"""
+This script gathers all of the files needed to build the publication.
+These files do not all exist in any single commit in the repository,
+because the publication needs to include versions of the `index.ipynb` notebook
+for each git tag.
+
+This script executes the following steps:
+- Copies the `index.ipynb` notebook from each tag to a `_freeze/index_v{tag}.ipynb` file.
+- Copies the `_freeze/index` directory from each tag to a `_freeze/index_v{tag}` directory.
+- Updates the `_quarto.yml` file to include a `version-control` item for each tag.
+"""
+
+import argparse
+import shutil
+import subprocess
+from contextlib import contextmanager
+from pathlib import Path
+
+import yaml
+
+
+def get_versioned_notebook_path(tag: str) -> Path:
+    """Get the path to the versioned `index.ipynb` notebook for a given tag."""
+    return Path(f"index_{tag}.ipynb")
+
+
+def get_versioned_freeze_directory_path(tag: str) -> Path:
+    """Get the path to the versioned `_freeze/index` directory for a given tag."""
+    return Path(f"_freeze/index_{tag}")
+
+
+@contextmanager
+def git_checkout(ref: str):
+    original_ref = (
+        subprocess.check_output(["git", "rev-parse", "--abbrev-ref", "HEAD"])
+        .decode("utf-8")
+        .strip()
+    )
+
+    try:
+        subprocess.run(["git", "checkout", ref], check=True)
+        yield
+    finally:
+        subprocess.run(["git", "checkout", original_ref], check=True)
+
+
+def get_tags() -> list[str]:
+    """Get a list of all git tags."""
+    result = subprocess.run(["git", "tag"], capture_output=True, text=True, check=True)
+    return result.stdout.splitlines()
+
+
+def copy_notebook(tag: str, dry_run: bool) -> None:
+    """Copy the `index.ipynb` notebook for a given tag to a versioned notebook."""
+    src = Path("index.ipynb")
+    dst = get_versioned_notebook_path(tag)
+
+    if dry_run:
+        print(f"Would copy '{src}' to '{dst}'")
+        return
+
+    shutil.copy2(src, dst)
+
+
+def copy_freeze_directory(tag: str, dry_run: bool) -> None:
+    """Copy the `_freeze/index` directory for a given tag to a versioned directory."""
+    src = Path("_freeze/index")
+    dst = get_versioned_freeze_directory_path(tag)
+
+    if dry_run:
+        print(f"Would copy '{src}' to '{dst}'")
+        return
+
+    shutil.copytree(src, dst, dirs_exist_ok=True)
+
+
+def update_index_notebook_and_freeze_directory(tag: str, dry_run: bool) -> None:
+    """
+    Rename the most recent tagged version of the notebook and its freeze directory
+    to `index.ipynb` and `_freeze/index`, respectively.
+    """
+    notebook_src = get_versioned_notebook_path(tag)
+    notebook_dst = Path("index.ipynb")
+
+    freeze_src = get_versioned_freeze_directory_path(tag)
+    freeze_dst = Path("_freeze/index")
+
+    if dry_run:
+        print(f"Would move '{notebook_src}' to '{notebook_dst}'")
+        print(f"Would move '{freeze_src}' to '{freeze_dst}'")
+        return
+
+    notebook_dst.unlink()
+    notebook_src.replace(notebook_dst)
+
+    shutil.rmtree(freeze_dst, ignore_errors=True)
+    freeze_src.replace(freeze_dst)
+
+
+def update_quarto_yaml(most_recent_tag: str, previous_tags: list[str], dry_run: bool) -> None:
+    """Update the _quarto.yml file to include menu items for each tagged release."""
+    yaml_path = Path("_quarto.yml")
+    content = yaml.safe_load(yaml_path.read_text())
+
+    most_recent_version_item = {
+        "text": f"{most_recent_tag} (latest)",
+        # The link for the most recent version is always `index.ipynb`.
+        # (This version of the notebook is renamed to `index.ipynb` elsewhere in this script.)
+        "href": "index.ipynb",
+    }
+    previous_version_items = [
+        {"text": tag, "href": str(get_versioned_notebook_path(tag))} for tag in previous_tags
+    ]
+
+    if dry_run:
+        print(f"Would update '{yaml_path}' with the following menu items:")
+        print(f"  - {most_recent_version_item}")
+        for item in previous_version_items:
+            print(f"  - {item}")
+        return
+
+    # Insert the new items.
+    for item in content["website"]["navbar"]["left"]:
+        if "version-control" in item.get("text", ""):
+            item["menu"] = [most_recent_version_item] + previous_version_items
+
+    yaml_path.write_text(yaml.dump(content, sort_keys=False, allow_unicode=True))
+
+
+def main() -> None:
+    """
+    Entrypoint for the script.
+
+    CLI args:
+        --dry-run: Print the actions that would be taken without actually taking them.
+            This is intended to be used when running this script locally during development,
+            as a way to preview the changes the script would make to the working directory.
+    """
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dry-run", action="store_true")
+    args = parser.parse_args()
+
+    tags = get_tags()
+    if not tags:
+        raise ValueError("No tags found")
+
+    for tag in tags:
+        print(f"Processing tag {tag}")
+        with git_checkout(tag):
+            copy_notebook(tag, dry_run=args.dry_run)
+            copy_freeze_directory(tag, dry_run=args.dry_run)
+
+    tags = sorted(tags, reverse=True)
+    most_recent_tag, *previous_tags = tags
+
+    update_index_notebook_and_freeze_directory(most_recent_tag, dry_run=args.dry_run)
+    update_quarto_yaml(most_recent_tag, previous_tags, dry_run=args.dry_run)
+
+
+if __name__ == "__main__":
+    main()