[Documentation]: Adding advanced tutorial and improvements to documentation #121
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 — Build & Preview | |
| on: | |
| push: | |
| branches: [ main ] # regular prod deploy | |
| paths: | |
| - 'mkdocs.yml' | |
| - 'docs/**' | |
| pull_request: # preview only when docs are touched | |
| branches: [ '**' ] | |
| paths: | |
| - 'mkdocs.yml' | |
| - 'docs/**' | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| outputs: | |
| short_sha: ${{ steps.sha.outputs.short }} | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: { fetch-depth: 0 } | |
| - uses: actions/setup-python@v5 | |
| with: { python-version: '3.x' } | |
| - uses: astral-sh/setup-uv@v6 | |
| - name: Install mesa-frames + docs deps | |
| run: | | |
| uv pip install --system . | |
| uv pip install --group docs --system | |
| - name: Convert jupytext .py notebooks to .ipynb | |
| run: | | |
| set -euxo pipefail | |
| # Convert any jupytext .py files to .ipynb without executing them. | |
| # Enable nullglob so the pattern expands to empty when there are no matches | |
| # and globstar so we recurse into subdirectories (e.g., user-guide/). | |
| shopt -s nullglob globstar || true | |
| files=(docs/general/**/*.py) | |
| if [ ${#files[@]} -eq 0 ]; then | |
| echo "No jupytext .py files found under docs/general" | |
| else | |
| for src in "${files[@]}"; do | |
| [ -e "$src" ] || continue | |
| dest="${src%.py}.ipynb" | |
| echo "Converting $src -> $dest" | |
| # jupytext will write the .ipynb alongside the source file | |
| uv run jupytext --to notebook "$src" | |
| done | |
| fi | |
| - name: Build MkDocs site | |
| run: uv run mkdocs build --config-file mkdocs.yml --site-dir ./site | |
| - name: Build Sphinx docs (API) | |
| run: uv run sphinx-build -b html docs/api site/api | |
| - name: Short SHA | |
| id: sha | |
| run: echo "short=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT" | |
| - name: Upload site artifact | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: site | |
| path: site | |
| deploy-main: | |
| needs: build | |
| if: github.event_name == 'push' && github.ref == 'refs/heads/main' | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/download-artifact@v4 | |
| with: { name: site, path: site } | |
| - name: Deploy to GitHub Pages (main) | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_branch: gh-pages | |
| publish_dir: ./site | |
| force_orphan: true | |
| deploy-preview: | |
| needs: build | |
| if: github.event_name == 'pull_request' | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/download-artifact@v4 | |
| with: { name: site, path: site } | |
| - name: Deploy preview under subfolder | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_branch: gh-pages | |
| publish_dir: ./site | |
| destination_dir: preview/${{ github.head_ref || github.ref_name }}/${{ needs.build.outputs.short_sha }} | |
| keep_files: true # keep previous previews | |
| # DO NOT set force_orphan here | |
| - name: Print preview URL | |
| run: | | |
| echo "Preview: https://${{ github.repository_owner }}.github.io/$(basename ${{ github.repository }})/preview/${{ github.head_ref || github.ref_name }}/${{ needs.build.outputs.short_sha }}/" |