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,20 @@ jobs:
     with:
       runs-on: ubuntu-latest
 
-  docs:
-    uses: ./.github/workflows/_docs.yml
-    permissions:
-      contents: write
+  install-graphviz:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install system packages
+        run: sudo apt-get update && sudo apt-get install -y graphviz
+
+  docs: # Call the docs building workflow directly
+    needs: install-graphviz
+    uses: DiamondLightSource/myst-version-switcher-plugin/.github/workflows/docs.yml@v0.27.0
+    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 +41,7 @@ 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.27.0
     permissions:
-      contents: write
+      contents: write # create the Release + attach assets

.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish
+
+on:
+  # matches ci.yml's `name:`, NOT its filename
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+
+  # fork-PR previews and manual re-deploys
+  workflow_dispatch:
+    inputs:
+      pr:
+        description: "Fork PR to approve + preview (empty = re-deploy)"
+        required: false
+        default: ""
+
+jobs:
+  publish:
+    # Both guards fail OPEN — copy them verbatim.
+    #   conclusion == 'success' : workflow_run fires on failures too
+    #   head_repository == this repo : workflow_run holds a WRITE token even when a
+    #     fork's PR triggered it (the pwn-request shape)
+    # The repository check keeps forks of blueapi from publishing to their own Pages.
+    if: >-
+      github.repository == 'DiamondLightSource/blueapi' &&
+      (github.event_name == 'workflow_dispatch' ||
+       (github.event.workflow_run.conclusion == 'success' &&
+        github.event.workflow_run.head_repository.full_name == github.repository))
+    uses: DiamondLightSource/myst-version-switcher-plugin/.github/workflows/publish-gh-pages.yml@v0.27.0
+    with:
+      pr: ${{ inputs.pr }}
+      max-releases: "30"
+      max-prs: "20"
+    permissions:
+      contents: read
+      actions: read      # gather cross-run docs artifacts
+      pages: write
+      id-token: write
+      statuses: write    # record the fork-preview approval / preview link

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/pyproject.toml.jinja

@@ -53,8 +53,10 @@ version_file = "src/{{ package_name }}/_version.py"
 typeCheckingMode = "strict"
 {% else %}
 typeCheckingMode = "standard"
-{% endif %}reportMissingImports = false # Ignore missing stubs in imported modules
-{% endif %}{% if type_checker=="mypy" %}
+{% endif %}
+reportMissingImports = false # Ignore missing stubs in imported modules
+{% endif %}
+{% if type_checker=="mypy" %}
 [tool.mypy]
 ignore_missing_imports = true # Ignore missing stubs in imported modules
 {% endif %}

template/renovate.json.jinja

@@ -22,15 +22,13 @@
         "actions/checkout",
         "astral-sh/setup-uv",
         "actions/upload-artifact",
-        "actions/download-artifact",
-        "softprops/action-gh-release",
         "codecov/codecov-action"{% if docker %},
         "docker/setup-buildx-action",
         "docker/login-action",
         "docker/build-push-action",
         "docker/metadata-action"{% endif %}{% if pypi %},
-        "pypa/gh-action-pypi-publish"{% endif %}{% if sphinx %},
-        "peaceiris/actions-gh-pages"{% endif %}
+        "pypa/gh-action-pypi-publish",
+        "actions/download-artifact"{% endif %}
       ],
       "matchManagers": [
         "github-actions"

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:
@@ -36,11 +34,20 @@ jobs:
       contents: read
       packages: write
 {% endraw %}{% endif %}{% if sphinx %}
+  install-graphviz:
+  runs-on: ubuntu-latest
+  steps:
+    - name: Install system packages
+      run: sudo apt-get update && sudo apt-get install -y graphviz
+
   docs:
-    uses: ./.github/workflows/_docs.yml
-    permissions:
-      contents: write
-{% endif %}
+    uses: DiamondLightSource/myst-version-switcher-plugin/.github/workflows/docs.yml@v0.27.0
+    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 +61,6 @@ 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.27.0
     permissions:
       contents: write

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

@@ -0,0 +1,39 @@
+name: Publish
+
+on:
+  # matches ci.yml's `name:`, NOT its filename
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+
+  # fork-PR previews and manual re-deploys
+  workflow_dispatch:
+    inputs:
+      pr:
+        description: "Fork PR to approve + preview (empty = re-deploy)"
+        required: false
+        default: ""
+
+jobs:
+  publish:
+    # Both guards fail OPEN — copy them verbatim.
+    #   conclusion == 'success' : workflow_run fires on failures too
+    #   head_repository == this repo : workflow_run holds a WRITE token even when a
+    #     fork's PR triggered it (the pwn-request shape)
+    # The repository check keeps forks of blueapi from publishing to their own Pages.
+    if: >-
+      github.repository == 'DiamondLightSource/blueapi' &&
+      (github.event_name == 'workflow_dispatch' ||
+       (github.event.workflow_run.conclusion == 'success' &&
+        github.event.workflow_run.head_repository.full_name == github.repository))
+    uses: DiamondLightSource/myst-version-switcher-plugin/.github/workflows/publish-gh-pages.yml@v0.27.0
+    with:
+      pr: ${{ inputs.pr }}
+      max-releases: "30"
+      max-prs: "20"
+    permissions:
+      contents: read
+      actions: read      # gather cross-run docs artifacts
+      pages: write
+      id-token: write
+      statuses: write    # record the fork-preview approval / preview link

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,
 }