Merge pull request #5 from CSSFrancis/add-interactive-fitting-example #27
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: | |
| # Only one docs deployment should run at a time to avoid race conditions on | |
| # the gh-pages branch. | |
| concurrency: | |
| group: docs-${{ 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 | |
| # ── 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' | |
| 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 | |
| # ── 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 }} | |