ci: Change blueapi github pages site publishing

.github/workflows/ci.yml

@@ -40,10 +40,13 @@ jobs:
       contents: read
       packages: write
 
-  docs:
-    uses: ./.github/workflows/_docs.yml
-    permissions:
-      contents: write
+  docs: # Call the docs building workflow directly
+    uses: DiamondLightSource/myst-version-switcher-plugin/.github/workflows/docs.yml@v0.24
+    with:
+      # Whatever turns your sources into docs/_build/html at $BASE_URL. uv and Node
+      # are preinstalled, so: make docs · tox -e docs · npm ci && npm run docs
+      build-command: uv run --locked tox -e docs
+      html-dir: build/html
 
   dist:
     uses: ./.github/workflows/_dist.yml
@@ -57,7 +60,21 @@ jobs:
 
   release:
     needs: [dist, test, docs]
-    if: github.ref_type == 'tag'
-    uses: ./.github/workflows/_release.yml
+    if: github.ref_type == 'tag' # tag pushes only
+    uses: DiamondLightSource/myst-version-switcher-plugin/.github/workflows/release.yml@v0.24
+    permissions:
+      contents: write # create the Release + attach assets
+
+  publish:
+    needs: [docs]
+    # don't publish a pages site in the fork's org
+    if: github.repository == 'DiamondLightSource/blueapi'
+    uses: ./.github/workflows/publish-dispatch.yml # your workflow (below)
+    with:
+      version-name: ${{ needs.docs.outputs.version-name }}
     permissions:
-      contents: write
+      contents: read
+      actions: write
+      pages: write
+      id-token: write
+      statuses: write

.github/workflows/publish-dispatch.yml

@@ -0,0 +1,36 @@
+# .github/workflows/publish-dispatch.yml
+name: Publish (dispatch)
+on:
+  workflow_call: # ci.yml's `publish` job, for every event
+    inputs:
+      version-name: {required: false, default: "", type: string}
+  # tag re-dispatch + fork-PR preview + manual re-deploy
+  workflow_dispatch:
+    inputs:
+      pr:
+        description: "Fork PR to approve + preview (empty = re-deploy)"
+        required: false
+        default: ""
+      retry-until:
+        description: "Internal = epoch-second retry deadline. Don't set manually."
+        required: false
+        default: ""
+
+jobs:
+  publish:
+    uses: DiamondLightSource/myst-version-switcher-plugin/.github/workflows/publish.yml@v0.24
+    with:
+      # "" on dispatch → pure durable gather
+      version-name: ${{ inputs.version-name }}
+      # set (dispatch) → pin that fork head SHA
+      pr: ${{ inputs.pr }}
+      # the file the tag re-dispatch re-fires
+      dispatch-workflow: publish-dispatch.yml
+      # forwarded so the re-dispatch job's auto-retry can re-fire this shim
+      retry-until: ${{ inputs.retry-until }}
+    permissions:
+      contents: read
+      actions: write
+      pages: write
+      id-token: write
+      statuses: write

docs/conf.py

@@ -5,9 +5,8 @@
 https://www.sphinx-doc.org/en/master/usage/configuration.html
 """
 
+import os
 import sys
-from pathlib import Path
-from subprocess import check_output
 
 import requests
 
@@ -21,14 +20,7 @@
 # The full version, including alpha/beta/rc tags.
 release = blueapi.__version__
 
-# The short X.Y version.
-if "+" in release:
-    # Not on a tag, use branch name
-    root = Path(__file__).absolute().parent.parent
-    git_branch = check_output("git branch --show-current".split(), cwd=root)
-    version = git_branch.decode().strip()
-else:
-    version = release
+version = os.environ.get("VERSION_NAME", "local")
 
 extensions = [
     # Use this for generating API docs
@@ -172,7 +164,7 @@
         "version_match": version,
     },
     "check_switcher": False,
-    "navbar_end": ["theme-switcher", "icon-links", "version-switcher"],
+    "navbar_end": ["theme-switcher", "navbar-icon-links", "version-switcher"],
     "navigation_with_keys": False,
 }