From 466f3b8b8dd63bdfafcaa2e6824a9a66c2a601b0 Mon Sep 17 00:00:00 2001
From: Giovanni Torres <giovtorres@users.noreply.github.com>
Date: Fri, 17 Apr 2026 16:10:22 -0400
Subject: [PATCH] doc: build docs in CI

---
 .github/workflows/docs.yml | 90 ++++++++++++++++++++++++++++++++++++++
 doc_requirements.txt       |  2 +-
 scripts/build.sh           |  2 +-
 scripts/builddocs.sh       | 10 +++--
 4 files changed, 99 insertions(+), 5 deletions(-)
 create mode 100644 .github/workflows/docs.yml

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 00000000..b5a9655e
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,90 @@
+name: Docs
+
+env:
+  SLURM_DOCKER_IMAGE: giovtorres/slurm-docker:25.11.4-rl10
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  docs-build:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Pull Slurm container
+        run: docker pull ${{ env.SLURM_DOCKER_IMAGE }}
+
+      - name: Start Slurm container
+        run: docker compose up -d
+
+      - name: Build docs
+        run: docker exec slurmctl bash -ec "cd /pyslurm && scripts/builddocs.sh -j4 -s"
+
+      - name: Upload docs artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-site
+          path: site/
+          retention-days: 7
+          if-no-files-found: error
+
+  docs-deploy-dev:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Pull Slurm container
+        run: docker pull ${{ env.SLURM_DOCKER_IMAGE }}
+
+      - name: Start Slurm container
+        run: docker compose up -d
+
+      - name: Deploy dev docs
+        run: docker exec slurmctl bash -ec "cd /pyslurm && pip install -q -r doc_requirements.txt && scripts/build.sh -j4 -d && mike deploy dev --push --update-aliases"
+
+  docs-deploy-release:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release'
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Pull Slurm container
+        run: docker pull ${{ env.SLURM_DOCKER_IMAGE }}
+
+      - name: Start Slurm container
+        run: docker compose up -d
+
+      - name: Deploy versioned docs
+        run: docker exec slurmctl bash -ec "cd /pyslurm && pip install -q -r doc_requirements.txt && scripts/build.sh -j4 -d && mike deploy ${{ github.ref_name }} latest --update-aliases --push"
diff --git a/doc_requirements.txt b/doc_requirements.txt
index 1169bcaa..79f062a9 100644
--- a/doc_requirements.txt
+++ b/doc_requirements.txt
@@ -1,7 +1,7 @@
 cython>=3.0.11,<3.1
 wheel
 setuptools
-mkdocstrings[python]
+mkdocstrings[python]<2.0
 mike
 mkdocs-material
 mkdocs-awesome-pages-plugin
diff --git a/scripts/build.sh b/scripts/build.sh
index 0992d844..916395b7 100755
--- a/scripts/build.sh
+++ b/scripts/build.sh
@@ -22,7 +22,7 @@ done
 
 shift $((OPTIND-1))
 
-PY_VER=$(python -c "import sys; v=sys.version_info; print(f'{v.major}.{v.minor}')")
+PY_VER=$(python3 -c "import sys; v=sys.version_info; print(f'{v.major}.{v.minor}')")
 echo "Building with ${OPT_JOBS} cores"
 export PYSLURM_BUILD_JOBS="$OPT_JOBS"
 
diff --git a/scripts/builddocs.sh b/scripts/builddocs.sh
index 23e37ce3..665479ae 100755
--- a/scripts/builddocs.sh
+++ b/scripts/builddocs.sh
@@ -1,14 +1,18 @@
 #!/bin/bash
 
-usage() { echo "Usage: $0 [-j jobs]" 1>&2; exit 1; }
+usage() { echo "Usage: $0 [-j jobs] [-s]" 1>&2; exit 1; }
 
 OPT_JOBS=${PYSLURM_BUILD_JOBS:-1}
+OPT_STRICT=""
 
-while getopts ":j:" o; do
+while getopts ":j:s" o; do
     case "${o}" in
         j)
             OPT_JOBS=${OPTARG}
             ;;
+        s)
+            OPT_STRICT="--strict"
+            ;;
         *)
             usage
             ;;
@@ -19,4 +23,4 @@ shift $((OPTIND-1))
 
 pip install -r doc_requirements.txt
 scripts/build.sh -j${OPT_JOBS} -d
-mkdocs build
+mkdocs build ${OPT_STRICT}