Merge pull request #50 from CSSFrancis/release/v0.6.0 #165
Workflow file for this run
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: Docs | |
| on: | |
| push: | |
| # Publish to dev/ on every push to main … | |
| branches: [main] | |
| # … and to a versioned directory on every release tag. | |
| tags: ["v*.*.*"] | |
| pull_request: | |
| branches: [main] | |
| # Allow manual re-builds from the Actions tab. | |
| workflow_dispatch: | |
| # Per-ref grouping so a new push supersedes an in-flight BUILD of the same | |
| # ref (PR iterations, repeated pushes to main). This deliberately does NOT | |
| # serialise deployments: a push to main and its release tag are different | |
| # refs, so they land in different groups. The deploy job carries its own | |
| # ref-independent group for that — see below. | |
| concurrency: | |
| group: docs-build-${{ github.ref }} | |
| cancel-in-progress: true | |
| permissions: | |
| contents: write # needed to push to gh-pages | |
| jobs: | |
| # ── Build ────────────────────────────────────────────────────────────────── | |
| # Runs on every push and every pull request. Treats warnings as errors so | |
| # broken cross-references and bad docstrings are caught before merge. | |
| build: | |
| name: Build docs | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| # ── uv + Python ────────────────────────────────────────────────────── | |
| - name: Set up uv | |
| uses: astral-sh/setup-uv@v5 | |
| with: | |
| python-version: "3.13" | |
| enable-cache: true | |
| # ── Dependencies ───────────────────────────────────────────────────── | |
| # Install the package itself plus the [docs] optional-dependency group | |
| # (sphinx, pydata-sphinx-theme, sphinx-gallery, pillow, playwright). | |
| - name: Install dependencies (with docs extras) | |
| run: uv sync --extra docs | |
| # Playwright ships the Python bindings but NOT the browser binaries. | |
| # --with-deps also installs the OS-level shared libraries Chromium needs | |
| # (libglib2, libnss3, etc.) on bare Ubuntu runners. | |
| - name: Install Playwright browser | |
| run: uv run playwright install chromium --with-deps | |
| # ── Build Pyodide wheel ─────────────────────────────────────────────── | |
| # Produces docs/_static/wheels/anyplotlib-0.0.0-py3-none-any.whl so the | |
| # in-browser Pyodide bridge can install the exact source tree that built | |
| # these docs — no PyPI release required. | |
| - name: Build Pyodide wheel | |
| run: | | |
| mkdir -p docs/_static/wheels | |
| uv build --wheel --out-dir docs/_static/wheels/ | |
| # Rename to the stable sentinel name micropip expects for URL installs. | |
| cd docs/_static/wheels | |
| for f in anyplotlib-*.whl; do | |
| [ "$f" != "anyplotlib-0.0.0-py3-none-any.whl" ] && mv "$f" anyplotlib-0.0.0-py3-none-any.whl | |
| done | |
| # ── Sphinx build ───────────────────────────────────────────────────── | |
| # -W turns warnings into errors; --keep-going collects all of them. | |
| - name: Build HTML documentation | |
| run: | | |
| uv run sphinx-build -b html docs build/html -W --keep-going | |
| # ── Upload built HTML as an artifact so it can be inspected on PRs ── | |
| - name: Upload HTML artifact | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: docs-html | |
| path: build/html | |
| retention-days: 7 | |
| # ── Deploy ───────────────────────────────────────────────────────────────── | |
| # Only runs after a successful build on pushes to main or release tags. | |
| # Pull requests skip this job entirely. | |
| deploy: | |
| name: Deploy docs | |
| needs: build | |
| runs-on: ubuntu-latest | |
| # Skip deployment for pull requests. | |
| if: github.event_name != 'pull_request' | |
| # Every deploy pushes to the SAME branch (gh-pages), so they must be | |
| # serialised across refs, not per-ref. Releasing tags main and v* almost | |
| # simultaneously, which previously raced: whichever run pushed second was | |
| # rejected with "cannot lock ref 'refs/heads/gh-pages'" and its version | |
| # directory never appeared, while switcher.json still advertised it. | |
| # cancel-in-progress is false because these runs must QUEUE — cancelling | |
| # one would drop a version directory just as surely as the race did. | |
| concurrency: | |
| group: docs-deploy | |
| cancel-in-progress: false | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| # ── uv + Python ────────────────────────────────────────────────────── | |
| - name: Set up uv | |
| uses: astral-sh/setup-uv@v5 | |
| with: | |
| python-version: "3.13" | |
| enable-cache: true | |
| # ── Dependencies ───────────────────────────────────────────────────── | |
| - name: Install dependencies (with docs extras) | |
| run: uv sync --extra docs | |
| - name: Install Playwright browser | |
| run: uv run playwright install chromium --with-deps | |
| # ── Determine deployment target ────────────────────────────────────── | |
| # Release tag (refs/tags/v1.2.3) → destination = "v1.2.3" | |
| # Everything else (push to main, manual dispatch) → destination = "dev" | |
| - name: Determine deployment directory | |
| id: target | |
| shell: bash | |
| run: | | |
| if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then | |
| echo "dest_dir=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT" | |
| else | |
| echo "dest_dir=dev" >> "$GITHUB_OUTPUT" | |
| fi | |
| # ── Build Pyodide wheel ─────────────────────────────────────────────── | |
| - name: Build Pyodide wheel | |
| run: | | |
| mkdir -p docs/_static/wheels | |
| uv build --wheel --out-dir docs/_static/wheels/ | |
| cd docs/_static/wheels | |
| for f in anyplotlib-*.whl; do | |
| [ "$f" != "anyplotlib-0.0.0-py3-none-any.whl" ] && mv "$f" anyplotlib-0.0.0-py3-none-any.whl | |
| done | |
| # ── Sphinx build ───────────────────────────────────────────────────── | |
| - name: Build HTML documentation | |
| env: | |
| DOCS_VERSION: ${{ steps.target.outputs.dest_dir }} | |
| run: | | |
| uv run sphinx-build -b html docs build/html -W --keep-going | |
| # ── Deploy to gh-pages ─────────────────────────────────────────────── | |
| # keep_files: true preserves all existing directories on the branch so | |
| # versioned releases accumulate rather than overwriting each other. | |
| - name: Deploy to GitHub Pages | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./build/html | |
| destination_dir: ${{ steps.target.outputs.dest_dir }} | |
| keep_files: true | |
| commit_message: | | |
| docs: deploy ${{ steps.target.outputs.dest_dir }} @ ${{ github.sha }} | |
| # ── Deploy root files (redirect + switcher) ────────────────────────── | |
| # Places index.html and switcher.json at the root of gh-pages so the | |
| # bare URL redirects to dev/ and the version switcher is always reachable. | |
| - name: Deploy root redirect and switcher | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./docs/_root | |
| destination_dir: . | |
| keep_files: true | |
| commit_message: | | |
| docs: update root redirect and switcher.json @ ${{ github.sha }} | |