Move docs publishing into release workflow

Author: lukewilliamboswell

.github/workflows/release.yml

@@ -3,8 +3,8 @@ name: Release
 on:
   workflow_dispatch:
     inputs:
-      release_tag:
-        description: "Release tag, e.g. v0.12.0"
+      release_version:
+        description: "Release version, e.g. 0.11.0"
         required: true
         type: string
   pull_request:
@@ -113,6 +113,9 @@ jobs:
       - test-bundle
     runs-on: ubuntu-24.04
     if: github.event_name == 'workflow_dispatch'
+    outputs:
+      release_commit: ${{ steps.prepare_release.outputs.release_commit }}
+      release_tag: ${{ steps.prepare_release.outputs.release_tag }}
     permissions:
       contents: write
     defaults:
@@ -137,46 +140,96 @@ jobs:
         with:
           version: nightly-new-compiler
 
-      - name: Update example package URLs
+      - name: Prepare release docs and examples
+        id: prepare_release
         env:
           BUNDLE_FILENAME: ${{ needs.build-bundle.outputs.bundle_filename }}
-          RELEASE_TAG: ${{ github.event.inputs.release_tag }}
+          RAW_RELEASE_VERSION: ${{ github.event.inputs.release_version }}
           REF_TYPE: ${{ github.ref_type }}
         run: |
           if [ "$REF_TYPE" != "branch" ]; then
             echo "Release workflow must be run from a branch so it can commit updated example URLs."
             exit 1
           fi
 
+          RELEASE_VERSION="${RAW_RELEASE_VERSION#v}"
+          if [[ ! "$RELEASE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Release version must use x.y.z format, e.g. 0.11.0"
+            exit 1
+          fi
+
+          RELEASE_TAG="$RELEASE_VERSION"
           BUNDLE_URL="https://github.com/lukewilliamboswell/roc-parser/releases/download/${RELEASE_TAG}/${BUNDLE_FILENAME}"
           set +e
           python3 ci/update_example_parser_url.py "$BUNDLE_URL"
           UPDATE_STATUS=$?
           set -e
 
-          if [ "$UPDATE_STATUS" -eq 0 ]; then
-            git config user.name "github-actions[bot]"
-            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-            git add examples
-            git commit -m "Update examples for ${RELEASE_TAG}"
-            git push origin HEAD:${{ github.ref_name }}
-          elif [ "$UPDATE_STATUS" -eq 2 ]; then
+          if [ "$UPDATE_STATUS" -eq 2 ]; then
             echo "Example package URLs are already current."
-          else
+          elif [ "$UPDATE_STATUS" -ne 0 ]; then
             exit "$UPDATE_STATUS"
           fi
 
+          DOCS_ROOT=www ./docs.sh "$RELEASE_VERSION"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add examples www
+
+          if git diff --cached --quiet; then
+            echo "Release docs and example URLs are already current."
+          else
+            git commit -m "Prepare ${RELEASE_VERSION} release artifacts"
+            git push origin HEAD:${{ github.ref_name }}
+          fi
+
+          echo "release_commit=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+          echo "release_tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
+
       - name: Create release
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
           BUNDLE_FILE="dist/${{ needs.build-bundle.outputs.bundle_filename }}"
           ROC_VERSION=$(roc version)
-          TARGET_COMMIT=$(git rev-parse HEAD)
+          TARGET_COMMIT="${{ steps.prepare_release.outputs.release_commit }}"
+          RELEASE_TAG="${{ steps.prepare_release.outputs.release_tag }}"
 
-          gh release create "${{ github.event.inputs.release_tag }}" \
+          gh release create "$RELEASE_TAG" \
             "$BUNDLE_FILE" \
             --target "$TARGET_COMMIT" \
-            --title "${{ github.event.inputs.release_tag }}" \
+            --title "$RELEASE_TAG" \
             --generate-notes \
             --notes "Parser package bundle built with Roc $ROC_VERSION."
+
+  deploy-docs:
+    name: Deploy docs
+    needs: create-release
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch'
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Checkout release commit
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.create-release.outputs.release_commit }}
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload docs artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "./www"
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/www.yaml

@@ -27,7 +27,7 @@ Includes modules to parse the following (with various levels of maturity);
 
 See [lukewilliamboswell.github.io/roc-parser/](https://lukewilliamboswell.github.io/roc-parser/)
 
-Locally generate docs using `roc docs package/main.roc --output=www`.
+Locally generate versioned docs using `./docs.sh 0.11.0`.
 
 ## Contributing
 
@@ -44,3 +44,5 @@ CI skips `examples/markdown.roc` because the latest Roc nightly overflows the co
 ## Packaging
 
 Bundle the package for distribution using `scripts/bundle.sh --output-dir dist`.
+
+Run the release workflow from GitHub Actions with a release version such as `0.11.0`. It builds and tests the bundle, updates example package URLs, regenerates versioned docs, updates the docs redirect, creates the GitHub release, and deploys the docs to GitHub Pages.

README.md

@@ -1,7 +1,6 @@
 #!/usr/bin/env bash
 
-# https://vaneyckt.io/posts/safer_bash_scripts_with_set_euxo_pipefail/
-set -euxo pipefail
+set -euo pipefail
 
 # Function to validate version number format (x.y.z)
 validate_version() {
@@ -14,14 +13,46 @@ validate_version() {
 # Check if version argument is provided
 if [ $# -ne 1 ]; then
     echo "Usage: $0 <version>"
-    echo "Example: $0 0.12.0"
+    echo "Example: $0 0.11.0"
     exit 1
 fi
 
-VERSION=$1
+VERSION="${1#v}"
+DOCS_ROOT="${DOCS_ROOT:-www}"
+ROC_BIN="${ROC:-roc}"
+
+if [[ "$ROC_BIN" == */* ]]; then
+    ROC_BIN="$(cd "$(dirname "$ROC_BIN")" && pwd)/$(basename "$ROC_BIN")"
+fi
 
 # Validate version number
 validate_version "$VERSION"
 
-# Run roc docs with validated version
-roc docs package/main.roc --output="www/$VERSION"
+rm -rf "$DOCS_ROOT/$VERSION"
+mkdir -p "$DOCS_ROOT"
+
+"$ROC_BIN" docs package/main.roc --output="$DOCS_ROOT/$VERSION"
+
+cat > "$DOCS_ROOT/index.html" <<EOF
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Redirecting...</title>
+        <script>
+            window.location.href = "/roc-parser/$VERSION/";
+        </script>
+    </head>
+    <body>
+        <noscript>
+            <p>
+                If you are not automatically redirected, please
+                <a href="/roc-parser/$VERSION/">click here</a>.
+            </p>
+        </noscript>
+    </body>
+</html>
+EOF
+
+echo "Generated docs for $VERSION in $DOCS_ROOT/$VERSION"