Use srun for job execution on Slurm (#171)

* Use srun for job execution on Slurm

* Use sstat for resource stat collection

* Add step_nodes to resource requirements for multi-node srun steps

*  Add slurm_stats table

Author: daniel-thom

.github/scripts/gh-pages-commit.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Shared commit-and-push for gh-pages deployments.
+# Must be run from inside the gh-pages-deploy directory.
+#
+# Usage: gh-pages-commit.sh "Commit message"
+set -e
+
+COMMIT_MSG="${1:?Usage: gh-pages-commit.sh \"commit message\"}"
+
+git add -A
+if git diff --cached --quiet; then
+  echo "No changes to deploy"
+else
+  git commit -m "$COMMIT_MSG"
+  git push origin gh-pages
+fi

.github/scripts/gh-pages-setup.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Shared setup for gh-pages deployments.
+# Configures git and clones (or initializes) the gh-pages branch into ./gh-pages-deploy.
+#
+# Required environment variables:
+#   GITHUB_TOKEN  — access token for pushing to the repository
+#   GITHUB_REPOSITORY — owner/repo (e.g., NatLabRockies/torc)
+set -e
+
+REPO_URL="https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+
+git config --global user.name "github-actions[bot]"
+git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+git clone --depth 1 --branch gh-pages "$REPO_URL" gh-pages-deploy 2>/dev/null || {
+  # Branch doesn't exist yet — create it
+  mkdir gh-pages-deploy
+  cd gh-pages-deploy
+  git init
+  git checkout -b gh-pages
+  git remote add origin "$REPO_URL"
+  cd ..
+}
+
+cd gh-pages-deploy
+touch .nojekyll

.github/workflows/docs.yml

@@ -8,17 +8,17 @@ on:
       - 'docs/**'
       - '.github/workflows/docs.yml'
 
+# contents:write is required to push to the gh-pages branch directly
+# (the previous pages:write + id-token:write approach used the Pages API instead)
 permissions:
-  contents: read
-  pages: write
-  id-token: write
+  contents: write
 
 concurrency:
   group: "pages"
   cancel-in-progress: false
 
 jobs:
-  build:
+  deploy:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -35,23 +35,43 @@ jobs:
       - name: Build documentation
         run: |
           cd docs
+          # Override site-url for versioned path
+          sed -i 's|site-url = "/torc/"|site-url = "/torc/latest/"|' book.toml
           mdbook build
 
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
+      - name: Setup gh-pages branch
+        run: .github/scripts/gh-pages-setup.sh
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
 
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
-        with:
-          path: 'docs/book'
+      - name: Deploy latest docs
+        run: |
+          cd gh-pages-deploy
 
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+          # One-time: clean legacy Sphinx content
+          rm -rf _static _sources _images genindex.html objects.inv searchindex.js \
+                 py-modindex.html search.html .buildinfo
+
+          # Replace latest/ with new build
+          rm -rf latest
+          cp -r ../docs/book latest
+
+          # Root redirect
+          cp ../docs/redirect.html index.html
+
+          # Initialize versions.json if it doesn't exist
+          if [ ! -f versions.json ]; then
+            cat > versions.json << 'VJSON'
+          {
+            "latest_release": null,
+            "versions": [
+              {"version": "latest", "label": "latest (dev)", "path": "/torc/latest/"}
+            ]
+          }
+          VJSON
+          fi
+
+      - name: Commit and push
+        run: |
+          cd gh-pages-deploy
+          ../.github/scripts/gh-pages-commit.sh "Deploy docs from ${GITHUB_SHA::8}"

.github/workflows/release.yml

@@ -234,3 +234,136 @@ jobs:
           tags: |
             ${{ steps.meta.outputs.image }}:${{ steps.meta.outputs.version }}
             ${{ steps.meta.outputs.image }}:latest
+
+  deploy-docs:
+    name: Deploy Versioned Docs
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    concurrency:
+      group: "pages"
+      cancel-in-progress: false
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: '0.4.52'
+
+      - name: Install mdbook-mermaid
+        run: cargo install mdbook-mermaid@0.16.0
+
+      - name: Build documentation
+        run: |
+          cd docs
+          VERSION="${{ steps.version.outputs.version }}"
+          # Override site-url and edit-url for this release version
+          sed -i "s|site-url = \"/torc/\"|site-url = \"/torc/${VERSION}/\"|" book.toml
+          sed -i "s|edit-url-template = \"https://github.com/NatLabRockies/torc/edit/main/docs/{path}\"|edit-url-template = \"https://github.com/NatLabRockies/torc/tree/${VERSION}/docs/{path}\"|" book.toml
+          mdbook build
+
+      - name: Setup gh-pages branch
+        run: .github/scripts/gh-pages-setup.sh
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+
+      - name: Deploy versioned docs
+        run: |
+          cd gh-pages-deploy
+          VERSION="${{ steps.version.outputs.version }}"
+
+          # Copy build into versioned subdirectory
+          rm -rf "${VERSION}"
+          cp -r ../docs/book "${VERSION}"
+
+          # Root redirect (only if missing)
+          if [ ! -f index.html ]; then
+            cp ../docs/redirect.html index.html
+          fi
+
+          # Update versions.json using inline Python
+          python3 << 'PYEOF'
+          import json, os, re, shutil
+
+          version = os.environ.get("VERSION", "${{ steps.version.outputs.version }}")
+          versions_file = "versions.json"
+
+          # Load existing or create new
+          if os.path.exists(versions_file):
+              with open(versions_file) as f:
+                  data = json.load(f)
+          else:
+              data = {"latest_release": None, "versions": []}
+
+          # Ensure "latest (dev)" entry exists
+          has_latest = any(v["version"] == "latest" for v in data["versions"])
+          if not has_latest:
+              data["versions"].insert(0, {
+                  "version": "latest",
+                  "label": "latest (dev)",
+                  "path": "/torc/latest/"
+              })
+
+          # Remove existing entry for this version if present
+          data["versions"] = [v for v in data["versions"] if v["version"] != version]
+
+          # Add new version entry after "latest"
+          new_entry = {
+              "version": version,
+              "label": version,
+              "path": f"/torc/{version}/"
+          }
+
+          # Find insertion point: after "latest", before other versions
+          insert_idx = 1  # after "latest"
+          data["versions"].insert(insert_idx, new_entry)
+
+          # Sort release versions by semver (descending), keep "latest" first
+          def semver_key(v):
+              if v["version"] == "latest":
+                  return (999, 999, 999)
+              # Extracts major.minor.patch; pre-release suffixes are ignored for sorting
+              m = re.match(r"v?(\d+)\.(\d+)\.(\d+)", v["version"])
+              if m:
+                  return (int(m.group(1)), int(m.group(2)), int(m.group(3)))
+              return (0, 0, 0)
+
+          data["versions"].sort(key=semver_key, reverse=True)
+
+          # Update latest_release
+          data["latest_release"] = version
+
+          # Keep at most MAX_VERSIONS release versions (plus "latest").
+          # Older versions beyond this limit are pruned from versions.json and disk.
+          MAX_VERSIONS = 5
+          release_versions = [v for v in data["versions"] if v["version"] != "latest"]
+          if len(release_versions) > MAX_VERSIONS:
+              pruned = release_versions[MAX_VERSIONS:]
+              data["versions"] = [v for v in data["versions"] if v not in pruned]
+              # Delete directories for pruned versions
+              for p in pruned:
+                  dir_name = p["version"]
+                  if os.path.isdir(dir_name):
+                      shutil.rmtree(dir_name)
+                      print(f"Pruned old version: {dir_name}")
+
+          with open(versions_file, "w") as f:
+              json.dump(data, f, indent=2)
+              f.write("\n")
+
+          print(f"Updated versions.json: {json.dumps(data, indent=2)}")
+          PYEOF
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+
+      - name: Commit and push
+        run: |
+          cd gh-pages-deploy
+          ../.github/scripts/gh-pages-commit.sh "Deploy docs ${VERSION} from ${GITHUB_SHA::8}"
+        env:
+          VERSION: ${{ steps.version.outputs.version }}