From 6c5d6d150f67044a2e16064e25118830a22c4c21 Mon Sep 17 00:00:00 2001 From: Peter Feerick <5500713+pfeerick@users.noreply.github.com> Date: Fri, 23 Oct 2026 19:29:30 +1000 Subject: [PATCH] ci: use one shared publish/preview workflow on every branch All docs branches are MkDocs now, so the publish workflow no longer needs the GitBook import path or workflow_call: every branch carries the same file and builds itself. The latest release branch comes from the DOCS_LATEST_BRANCH repository variable (falling back to edgetx_2.12), so an older branch's copy can't take the "latest" alias back after a new release ships. Also adds preview-docs.yml, which uploads a Cloudflare preview for PRs into main or any edgetx_* branch. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/preview-docs.yml | 121 +++++++++++++++++++ .github/workflows/publish-versioned-docs.yml | 108 ++++++----------- 2 files changed, 160 insertions(+), 69 deletions(-) create mode 100644 .github/workflows/preview-docs.yml diff --git a/.github/workflows/preview-docs.yml b/.github/workflows/preview-docs.yml new file mode 100644 index 000000000..e1220aa67 --- /dev/null +++ b/.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--edgetx-lua-reference-guide.edgetx.workers.dev/ +# +# The PR is built as the version its base branch publishes (main -> "dev", +# edgetx_ -> "", 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}" diff --git a/.github/workflows/publish-versioned-docs.yml b/.github/workflows/publish-versioned-docs.yml index fb07e667a..cb05681cd 100644 --- a/.github/workflows/publish-versioned-docs.yml +++ b/.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_ -> "", 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 --push `). +# 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,49 +18,52 @@ 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 @@ -73,51 +71,24 @@ jobs: ;; 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]" @@ -125,13 +96,12 @@ jobs: - 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