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,12 @@ 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.28.0
+    with:
+      # Some of the docs need graphviz, so install it as well as running sphinx
+      build-command: sudo apt-get install -y graphviz && uv run --locked tox -e docs
+      html-dir: build/html
 
   example:
     needs: test
@@ -33,7 +33,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.28.0
     permissions:
-      contents: write
+      contents: write # create the Release + attach assets

.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+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:
+    # Run if the workflow has been manually dispatched or it was a
+    # successful CI run that did not come from a fork.
+    # Skip merge queue runs as they deploy the same commit as the PR commit
+    if: >-
+      (github.event_name == 'workflow_dispatch' ||
+       (github.event.workflow_run.conclusion == 'success' &&
+        github.event.workflow_run.event != 'merge_group' &&
+        github.event.workflow_run.head_repository.full_name == github.repository))
+    uses: DiamondLightSource/myst-version-switcher-plugin/.github/workflows/publish-gh-pages.yml@v0.28.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

copier.yml

@@ -163,3 +163,6 @@ _migrations:
           - echo This update will require you to login to pypi.org and make changes before you can make a new release to PyPI. If you do not have time to do this now, press CTRL+C to abort this update.
       after:
           - echo Visit https://diamondlightsource.github.io/python-copier-template/main/how-to/pypi.html to find out how to set up PyPI trusted publishing
+
+publish:
+    - echo: If your repo was using the `gh-pages` branch to publish docs, follow the [migration instructions](https://diamondlightsource.github.io/myst-version-switcher-plugin/main/how-to/migrate-from-gh-pages) to now use Github Actions.

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
@@ -110,9 +101,9 @@
 if not switcher_exists:
     print(
         "*** Can't read version switcher, is GitHub pages enabled? \n"
-        "    Once Docs CI job has successfully run once, set the "
-        "Github pages source branch to be 'gh-pages' at:\n"
-        f"    https://github.com/{github_user}/{github_repo}/settings/pages",
+        "    Set the Github pages source to 'GitHub Actions' at:\n"
+        f"    https://github.com/{github_user}/{github_repo}/settings/pages\n"
+        "    then CI will publish the docs on its next successful run.",
         file=sys.stderr,
     )
 
@@ -135,15 +126,15 @@
         "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
 html_context = {
     "github_user": github_user,
     "github_repo": github_repo,
-    "github_version": version,
+    "github_version": "main",
     "doc_path": "docs",
 }
 

docs/how-to/build-docs.md

@@ -41,8 +41,12 @@ $ tox -e docs-autobuild -- --watch tests
 (building-docs-in-ci)=
 ## Building docs in CI
 
-After a successful run of CI
+For a successful docs build, the source for the 'Build and Deployment' of the Github Pages should be set to GitHub Actions (Not 'Deploy from a branch'). This should be changes first and then the CI will publish.
 
 Settings > Pages
 
-![Setup GitHub Pages](../images/gh-pages-setup.png)
+![Setup GitHub Pages](../images/github-pages-actions-setup.png)
+
+If your repo was using the `gh-pages` branch to publish docs, follow the [migration instructions](https://diamondlightsource.github.io/myst-version-switcher-plugin/main/how-to/migrate-from-gh-pages) to now use Github Actions. 
+
+Docs are built using the [myst-version-switcher-plugin](https://github.com/DiamondLightSource/myst-version-switcher-plugin). 

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/renovate.json.jinja

@@ -22,15 +22,14 @@
         "actions/checkout",
         "astral-sh/setup-uv",
         "actions/upload-artifact",
-        "actions/download-artifact",
-        "softprops/action-gh-release",
+        "DiamondLightSource/myst-version-switcher-plugin",
         "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"