docs: group nav into tabs + Examples gallery #2
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: | |
| branches: [main] | |
| pull_request: | |
| # Least-privilege token scoped for the Pages deployment. | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| # Serialize deployments; don't cancel an in-flight one. | |
| concurrency: | |
| group: pages | |
| cancel-in-progress: false | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.12' | |
| cache: pip | |
| # Runtime deps (jax, etc.) are installed so the synthetic tutorial | |
| # notebooks under docs/tutorials/ can be executed at build time; ipykernel | |
| # provides the execution kernel. mkdocstrings itself uses griffe STATIC | |
| # analysis (no import), but executing the notebooks needs the real package. | |
| - name: Install dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install -e . | |
| pip install ipykernel mkdocs-material "mkdocstrings[python]" mkdocs-jupyter | |
| python -m ipykernel install --user --name python3 | |
| # --strict fails on any broken link or mkdocstrings warning (also gates | |
| # PRs). execute:true (mkdocs.yml) runs the docs/tutorials/ notebooks so | |
| # their plots render — CPU-only (no GPU on hosted runners; the tutorials | |
| # are small synthetic events). Outputs live only in the built site and are | |
| # never committed (source notebooks stay stripped by nbstripout). | |
| - name: Build site (strict, notebooks executed) | |
| env: | |
| JAX_PLATFORM_NAME: cpu | |
| run: mkdocs build --strict | |
| - uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: site | |
| deploy: | |
| # Publish only from main; PRs just build as a gate. | |
| if: github.ref == 'refs/heads/main' | |
| needs: build | |
| runs-on: ubuntu-latest | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - id: deployment | |
| uses: actions/deploy-pages@v4 |