ci: update docs publishing using myst-version-switcher-plugin

.github/workflows/ci.yml

@@ -1,12 +1,10 @@
 name: CI
 
 on:
-  push:
-    branches:
-      - main
-    tags:
-      - '*'
   pull_request:
+  push:
+    branches: [main]
+    tags: ["*"] # '*' never matches '/', so e.g. release/x tags don't build
 
 jobs:
   lint:
@@ -19,10 +17,13 @@ jobs:
     with:
       runs-on: ubuntu-latest
 
-  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.1
+    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
 
   example:
     needs: test
@@ -33,7 +34,21 @@ jobs:
 
   release:
     needs: [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.1
+    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/python-copier-template' && github.ref_type == 'tag' # publish only on tags
+    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

@@ -3,11 +3,9 @@
 # This file only contains a selection of the most common options. For a full
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
-
+import os
 import sys
 from importlib.metadata import version
-from pathlib import Path
-from subprocess import check_output
 
 import requests
 
@@ -19,14 +17,7 @@
 # The full version, including alpha/beta/rc tags.
 release = version(project)
 
-# 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 = [
     # For graphviz diagrams
@@ -135,8 +126,8 @@
         "json_url": switcher_json,
         "version_match": version,
     },
-    "check_switcher": True,
-    "navbar_end": ["theme-switcher", "icon-links", "version-switcher"],
+    "check_switcher": False,
+    "navbar_end": ["theme-switcher", "navbar-icon-links", "version-switcher"],
 }
 
 # A dictionary of values to pass into the template engine’s context for all pages

pyproject.toml

@@ -4,7 +4,9 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-copier-template"
+description = "Diamond's opinionated copier template for pure Python projects."
 dynamic = ["version"]
+readme = "README.md"
 requires-python = ">=3.11"
 
 [dependency-groups]

template/{% if git_platform=="github.com" %}.github{% endif %}/workflows/ci.yml.jinja

@@ -1,13 +1,11 @@
 name: CI
 
 on:
-  push:
-    branches:
-      - main
-    tags:
-      - '*'
   pull_request:
-
+  push:
+    branches:[main]
+    tags:['*']
+
 jobs:
 
   lint:
@@ -37,10 +35,13 @@ jobs:
       packages: write
 {% endraw %}{% endif %}{% if sphinx %}
   docs:
-    uses: ./.github/workflows/_docs.yml
-    permissions:
-      contents: write
-{% endif %}
+    uses: DiamondLightSource/myst-version-switcher-plugin/.github/workflows/docs.yml@v0.24.1
+    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
+  {% endif %}
   dist:
     uses: ./.github/workflows/_dist.yml
   {% if pypi %}
@@ -54,6 +55,20 @@ jobs:
   release:
     needs: [dist, test{% if sphinx %}, docs{% endif %}]
     if: github.ref_type == 'tag'
-    uses: ./.github/workflows/_release.yml
+    uses: DiamondLightSource/myst-version-switcher-plugin/.github/workflows/release.yml@v0.24.1
     permissions:
       contents: write
+  {% if sphinx %}{% raw %}
+  publish:
+    needs: [docs]
+    if: github.repository == 'DiamondLightSource/python-copier-template' && github.ref_type == 'tag' #publish only on tags
+    uses: ./.github/workflows/publish-dispatch.yml # your workflow (below)
+    with:
+      version-name: ${{ needs.docs.outputs.version-name }}
+    permissions:
+      contents: read
+      actions: write
+      pages: write
+      id-token: write
+      statuses: write
+  {% endraw %}{% endif %}

template/{% if git_platform=="github.com" %}.github{% endif %}/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.1
+    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

template/{% if sphinx %}docs{% endif %}/conf.py.jinja

@@ -168,7 +168,7 @@ html_theme_options = {
         "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,
 }