Merge branch 'main' into dev #74
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Build & Publish Docs | |
| on: | |
| push: | |
| branches: [main, dev] | |
| tags: | |
| - 'v*' # e.g., v1.2.3 | |
| workflow_dispatch: | |
| permissions: | |
| contents: write | |
| concurrency: | |
| group: docs-${{ github.ref }} | |
| cancel-in-progress: false | |
| jobs: | |
| docs: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Check out repo | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 # need full history for tags and gh-pages | |
| - name: Set up Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.x' | |
| cache: 'pip' | |
| - name: Install dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install mkdocs mkdocs-material mkdocstrings[python] mike | |
| - name: Build docs (sanity check) | |
| run: mkdocs build --strict | |
| - name: Configure git author (for mike) | |
| run: | | |
| git config user.name "github-actions[bot]" | |
| git config user.email "github-actions[bot]@users.noreply.github.com" | |
| - name: Ensure local gh-pages branch exists | |
| run: | | |
| if git ls-remote --exit-code --heads origin gh-pages >/dev/null 2>&1; then | |
| git fetch origin gh-pages:gh-pages | |
| fi | |
| # --- Branch-based deployments --- | |
| - name: Publish dev branch as 'dev' | |
| if: github.ref_name == 'dev' | |
| run: mike deploy --push dev | |
| - name: Publish main branch build as 'main' | |
| if: github.ref_name == 'main' | |
| run: mike deploy --push main | |
| # --- Tag-based versioning: v1.2.3 -> 1.2.3 --- | |
| - name: Publish tag as version | |
| if: startsWith(github.ref, 'refs/tags/v') | |
| env: | |
| TAG: ${{ github.ref_name }} # e.g. v1.2.3 | |
| run: | | |
| VERSION="${TAG#v}" | |
| echo "Deploying version ${VERSION}" | |
| mike deploy --push "${VERSION}" | |
| - name: Update 'latest'/'stable' if this tag is newest release | |
| if: startsWith(github.ref, 'refs/tags/v') | |
| env: | |
| TAG: ${{ github.ref_name }} | |
| run: | | |
| set -euo pipefail | |
| VERSION="${TAG#v}" | |
| # Ignore pre-releases (contains a dash, e.g., 1.2.3-rc1) | |
| if echo "$VERSION" | grep -q '-'; then | |
| echo "Pre-release tag detected ($VERSION); not updating aliases." | |
| exit 0 | |
| fi | |
| # Determine newest semver tag in repo (ignores pre-releases) | |
| LATEST_TAG="$(git tag -l 'v[0-9]*' | grep -v '-' | sort -V | tail -n1 || true)" | |
| LATEST_VERSION="${LATEST_TAG#v}" | |
| echo "Latest tag in repo: ${LATEST_VERSION:-<none>}" | |
| if [ "$LATEST_VERSION" = "$VERSION" ]; then | |
| echo "This is the newest release; updating aliases and default." | |
| mike deploy --push --update-aliases "$VERSION" latest stable | |
| mike set-default --push "$VERSION" | |
| else | |
| echo "Not the newest release; leaving aliases as-is." | |
| fi | |
| # Optional: keep the built 'site' dir as a CI artifact (debugging) | |
| - name: Upload built site as artifact (optional) | |
| if: always() | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: site-${{ github.ref_name }} | |
| path: site |