Add files via upload #11
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
| # .github/workflows/deploy-docs.yml | |
| name: Deploy Docs (on latest push to main branch) | |
| # It builds and deploys the latest version of the documentation to GitHub Pages. | |
| # IMPORTANT: Ensure Repo Settings / Pages / Build and deployment / Set Source to `GitHub Actions`. | |
| # CI PHASES A-B-C-D: | |
| # - Assemble: Install dependencies, verify environment setup | |
| # - Baseline: Core validation (types exist, lint passes, tests pass) | |
| # - Coverage: Generate reports and upload artifacts | |
| # - Deploy: Build package and docs (sanity checks for release readiness) | |
| on: | |
| push: | |
| branches: [main] | |
| workflow_dispatch: | |
| permissions: | |
| contents: write # gh-pages deployment | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: pages-${{ github.ref }} | |
| cancel-in-progress: true | |
| env: | |
| PYTHONUNBUFFERED: "1" # real-time logging | |
| PYTHONIOENCODING: "utf-8" | |
| jobs: | |
| deploy: | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 30 | |
| steps: | |
| # ------------------- ASSEMBLE ------------------- | |
| - name: A1) Checkout (with tag history) | |
| uses: actions/checkout@v5 | |
| with: | |
| fetch-depth: 0 # Full history for tags | |
| - name: A2) Install uv (with caching) | |
| uses: astral-sh/setup-uv@v7 | |
| with: | |
| enable-cache: true | |
| - name: A3) Pin Python version for consistency | |
| run: uv python pin 3.12 | |
| - name: A4) Sync to install dependencies | |
| run: uv sync --extra dev --extra docs --upgrade | |
| # ------------------- BASELINE CHECKS ------------------- | |
| - name: B1) Fail fast if no MkDocs configuration | |
| run: | | |
| if [ -f "mkdocs.yml" ] || [ -f "mkdocs.yaml" ]; then | |
| echo "MkDocs configuration found. Proceeding." | |
| else | |
| echo "ERROR: mkdocs.yml not found." | |
| echo "If you do not want documentation deployment," | |
| echo "delete .github/workflows/deploy-docs.yml (or add mkdocs.yml)." | |
| exit 1 | |
| fi | |
| # ------------ DEPLOY ------------------ | |
| - name: D1) Build docs (mkdocs --strict) | |
| run: uv run mkdocs build --strict | |
| - name: D2) Assert site artifact exists | |
| run: | | |
| test -d site && test -f site/index.html || { | |
| echo "ERROR: MkDocs build produced no site/index.html" | |
| exit 1 | |
| } | |
| - name: D3) Upload site as artifact | |
| uses: actions/upload-pages-artifact@v4 | |
| with: | |
| path: ./site | |
| - name: D4) Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |