ci: use one shared publish/preview workflow on every branch

.github/workflows/preview-docs.yml

@@ -0,0 +1,121 @@
+# Builds a preview of the docs for each pull request and uploads it to
+# Cloudflare as a Worker *version* with a preview alias. Production keeps
+# serving the deployed version; the preview is only reachable at
+#   https://pr-<number>-edgetx-lua-reference-guide.edgetx.workers.dev/
+#
+# The PR is built as the version its base branch publishes (main -> "dev",
+# edgetx_<x.y> -> "<x.y>", plus "latest" for the latest release branch) on
+# top of the current gh-pages tree, so the preview is the whole site with
+# that one version replaced. Nothing is pushed to gh-pages.
+#
+# Only runs for PRs from branches in this repo: fork PRs don't get the
+# Cloudflare secrets, and building untrusted code with them available
+# would be unsafe anyway.
+name: Preview Docs
+
+on:
+  pull_request:
+    branches:
+      - main
+      - "edgetx_*"
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: preview-docs-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  preview:
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Resolve version metadata
+        id: version
+        shell: bash
+        env:
+          LATEST_BRANCH: ${{ vars.DOCS_LATEST_BRANCH || 'edgetx_2.12' }}
+        run: |
+          case "${GITHUB_BASE_REF}" in
+            main)
+              version_id="dev"
+              title="Dev"
+              ;;
+            edgetx_[0-9]*.[0-9]*)
+              version_id="${GITHUB_BASE_REF#edgetx_}"
+              title="${version_id}"
+              ;;
+            *)
+              echo "Unsupported base branch: ${GITHUB_BASE_REF}" >&2
+              exit 1
+              ;;
+          esac
+
+          if [[ "${GITHUB_BASE_REF}" == "${LATEST_BRANCH}" ]]; then
+            aliases="${version_id} latest"
+          else
+            aliases="${version_id}"
+          fi
+
+          {
+            echo "version_id=${version_id}"
+            echo "title=${title}"
+            echo "aliases=${aliases}"
+            echo "alias=pr-${{ github.event.pull_request.number }}"
+          } >> "${GITHUB_OUTPUT}"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Sync docs dependencies
+        run: uv sync
+
+      - name: Configure git author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Build preview into local gh-pages
+        env:
+          DOCS_EDIT_URI: edit/${{ github.head_ref }}/website/md-docs/
+        run: |
+          git branch -f gh-pages origin/gh-pages
+          uv run mike deploy --update-aliases --title "${{ steps.version.outputs.title }}" ${{ steps.version.outputs.aliases }}
+
+      - name: Export gh-pages tree for Cloudflare
+        run: |
+          rm -rf .site-publish
+          mkdir .site-publish
+          git archive gh-pages | tar -x -C .site-publish
+
+      - name: Upload preview version to Cloudflare Workers
+        uses: cloudflare/wrangler-action@v4
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: versions upload --preview-alias ${{ steps.version.outputs.alias }} --message "PR #${{ github.event.pull_request.number }} @ ${{ github.event.pull_request.head.sha }}"
+
+      - name: Comment preview link on the PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          url="https://${{ steps.version.outputs.alias }}-edgetx-lua-reference-guide.edgetx.workers.dev/${{ steps.version.outputs.version_id }}/"
+          body="📖 **Docs preview:** ${url}
+
+          Built from ${HEAD_SHA::7} as the \`${{ steps.version.outputs.version_id }}\` version, on top of the currently published site."
+          gh pr comment "${PR_NUMBER}" --edit-last --create-if-none --body "${body}"

.github/workflows/publish-versioned-docs.yml

@@ -1,17 +1,12 @@
-# Publishes the maintained docs via `mike deploy` on every push:
-#   main        -> "dev"
-#   edgetx_2.12 -> "2.12" + "latest"
-#   edgetx_2.11 -> "2.11" (LTS)
+# Publishes each docs branch via `mike deploy` on every push:
+#   main         -> "dev"
+#   edgetx_<x.y> -> "<x.y>", plus "latest" for the latest release branch
 #
-# main and edgetx_2.12 carry the MkDocs site and build from their own
-# mkdocs.yml. GitBook-era branches (2.4-2.11) have no MkDocs config or
-# tooling, so for those the job checks out the tooling from the latest
-# release branch and converts the pushed branch's content with
-# tools/import_legacy_gitbook.py before deploying. A push to edgetx_2.11
-# can only run workflows committed on edgetx_2.11, so that branch carries
-# a small caller workflow that invokes this one via workflow_call.
-# 2.4-2.10 are frozen and were deployed by hand the same way (import, then
-# `mike deploy --config-file <generated config> --push <version>`).
+# Every branch carries its own MkDocs site (mkdocs.yml + website/md-docs/)
+# and an identical copy of this workflow, so a push builds the branch it
+# came from. The latest release branch comes from the DOCS_LATEST_BRANCH
+# repository variable (falling back to edgetx_2.12), so moving "latest" to
+# a new release is a settings change rather than an edit on every branch.
 #
 # mike keeps the accumulated versioned site on the gh-pages branch; after
 # each deploy, the full gh-pages tree is published to Cloudflare Workers
@@ -23,115 +18,90 @@ on:
   push:
     branches:
       - main
-      - edgetx_2.12
+      - "edgetx_*"
   workflow_dispatch:
-  workflow_call:
 
 permissions:
   contents: write
 
+# Every run rewrites gh-pages and then uploads the whole tree, so run them
+# one at a time to avoid racing mike or publishing a stale snapshot.
+concurrency:
+  group: publish-versioned-docs
+  cancel-in-progress: false
+
 jobs:
   publish:
     runs-on: ubuntu-latest
 
-    # Every run rewrites gh-pages and then uploads the whole tree, so run
-    # them one at a time to avoid racing mike or publishing a stale
-    # snapshot. This is job-level rather than workflow-level so it also
-    # applies when called from another branch's workflow.
-    concurrency:
-      group: publish-versioned-docs
-      cancel-in-progress: false
-
     steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
       - name: Resolve version metadata
         id: version
         shell: bash
+        env:
+          LATEST_BRANCH: ${{ vars.DOCS_LATEST_BRANCH || 'edgetx_2.12' }}
         run: |
-          # In a workflow_call run, github.ref_name is the caller's branch.
           branch="${GITHUB_REF_NAME}"
-          latest_branch="edgetx_2.12"
 
           case "${branch}" in
             main)
               version_id="dev"
               title="Dev"
-              source="mkdocs"
-              ;;
-            edgetx_2.12)
-              version_id="2.12"
-              title="2.12"
-              source="mkdocs"
               ;;
-            edgetx_2.[4-9]|edgetx_2.1[01])
+            edgetx_[0-9]*.[0-9]*)
               version_id="${branch#edgetx_}"
               title="${version_id}"
-              source="gitbook"
               ;;
             *)
               echo "Unsupported branch: ${branch}" >&2
               exit 1
               ;;
           esac
 
-          if [[ "${branch}" == "${latest_branch}" ]]; then
+          if [[ "${branch}" == "${LATEST_BRANCH}" ]]; then
             aliases="${version_id} latest"
+            is_latest="true"
           else
             aliases="${version_id}"
-          fi
-
-          if [[ "${source}" == "gitbook" ]]; then
-            tools_ref="${latest_branch}"
-            config_file=".site-legacy-generated/${version_id}/mkdocs.yml"
-          else
-            tools_ref="${GITHUB_SHA}"
-            config_file="mkdocs.yml"
+            is_latest="false"
           fi
 
           {
-            echo "branch=${branch}"
             echo "version_id=${version_id}"
             echo "title=${title}"
             echo "aliases=${aliases}"
-            echo "source=${source}"
-            echo "tools_ref=${tools_ref}"
-            echo "config_file=${config_file}"
+            echo "is_latest=${is_latest}"
           } >> "${GITHUB_OUTPUT}"
 
-      - name: Check out source
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ steps.version.outputs.tools_ref }}
-          fetch-depth: 0
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
       - name: Sync docs dependencies
         run: uv sync
 
-      - name: Import GitBook content
-        if: steps.version.outputs.source == 'gitbook'
-        run: uv run python tools/import_legacy_gitbook.py --ref "origin/${{ steps.version.outputs.branch }}"
-
       - name: Configure git author
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
       - name: Publish docs with mike
         env:
-          # "Edit this page" should open the branch this version is built
-          # from. Imported GitBook configs set their own empty edit_uri.
-          DOCS_EDIT_URI: edit/${{ steps.version.outputs.branch }}/website/md-docs/
-        run: uv run mike deploy --push --update-aliases --config-file "${{ steps.version.outputs.config_file }}" --title "${{ steps.version.outputs.title }}" ${{ steps.version.outputs.aliases }}
+          # "Edit this page" should open the branch this version is built from.
+          DOCS_EDIT_URI: edit/${{ github.ref_name }}/website/md-docs/
+        run: uv run mike deploy --push --update-aliases --title "${{ steps.version.outputs.title }}" ${{ steps.version.outputs.aliases }}
 
       - name: Set default docs version
-        if: steps.version.outputs.branch == 'edgetx_2.12'
+        if: steps.version.outputs.is_latest == 'true'
         run: uv run mike set-default --push latest
 
       - name: Export gh-pages tree for Cloudflare