diff --git a/.github/workflows/publish-versioned-docs.yml b/.github/workflows/publish-versioned-docs.yml index 7745e26c5..fb07e667a 100644 --- a/.github/workflows/publish-versioned-docs.yml +++ b/.github/workflows/publish-versioned-docs.yml @@ -1,12 +1,17 @@ -# Publishes the actively-maintained docs (main -> "dev", edgetx_2.12 -> -# "latest") via `mike deploy` on every push. Legacy GitBook-era versions -# (2.4-2.11) are NOT handled here -- this job assumes a working mkdocs.yml -# already exists at the branch root when triggered, but none of those -# branches ever had one committed (they're raw GitBook content; building -# them requires running tools/import_legacy_gitbook.py first, which this -# workflow doesn't do). They're deployed manually instead: run the import -# script against each legacy branch/ref, then `mike deploy --config-file -# --push `. See MIGRATION-PLAN.md. +# Publishes the maintained docs via `mike deploy` on every push: +# main -> "dev" +# edgetx_2.12 -> "2.12" + "latest" +# edgetx_2.11 -> "2.11" (LTS) +# +# 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 `). # # mike keeps the accumulated versioned site on the gh-pages branch; after # each deploy, the full gh-pages tree is published to Cloudflare Workers @@ -20,82 +25,47 @@ on: - main - edgetx_2.12 workflow_dispatch: + workflow_call: permissions: contents: write -# Pushes to main and edgetx_2.12 both rewrite gh-pages and then upload 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 - 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" + # 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: Resolve version metadata id: version shell: bash 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) - version_id="2.4" - title="2.4" - ;; - edgetx_2.5) - version_id="2.5" - title="2.5" - ;; - edgetx_2.6) - version_id="2.6" - title="2.6" - ;; - edgetx_2.7) - version_id="2.7" - title="2.7" - ;; - edgetx_2.8) - version_id="2.8" - title="2.8" - ;; - edgetx_2.9) - version_id="2.9" - title="2.9" - ;; - edgetx_2.10) - version_id="2.10" - title="2.10" - ;; - edgetx_2.11) - version_id="2.11" - title="2.11" - ;; - main) - version_id="dev" - title="Dev" + edgetx_2.[4-9]|edgetx_2.1[01]) + version_id="${branch#edgetx_}" + title="${version_id}" + source="gitbook" ;; *) echo "Unsupported branch: ${branch}" >&2 @@ -109,15 +79,45 @@ jobs: 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" + 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}" } >> "${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,12 +125,13 @@ jobs: - name: Publish docs with mike env: - # "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 }} + # "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 }} - name: Set default docs version - if: github.ref_name == 'edgetx_2.12' + if: steps.version.outputs.branch == 'edgetx_2.12' run: uv run mike set-default --push latest - name: Export gh-pages tree for Cloudflare