del root data/ #23
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-zensical.yml (ALL-PY-REPOS) | |
| # ============================================================ | |
| # Updated: 2026-08-26 | |
| # | |
| # WHY: Build and deploy documentation to GitHub Pages on pushes to main. | |
| # REQ: Repo Settings -> Pages -> Build and deployment -> Source: | |
| # GitHub Actions | |
| # WHY: Without this setting, the deploy-pages action will fail with a 403. | |
| # REQ: Repository MUST contain .python-version. | |
| # WHY: The repository declares the Python version used locally and by CI. | |
| # REQ: Deployment MUST use the committed uv.lock without updating it. | |
| # Name shown in the repo Actions tab. | |
| name: Docs Deploy (Zensical) | |
| on: | |
| push: | |
| branches: [main] # WHY: Deploy docs on every push to GitHub branch `main`. | |
| workflow_dispatch: # WHY: Allow manual trigger from Actions tab. | |
| permissions: | |
| contents: read # WHY: Needed to checkout code. | |
| pages: write # WHY: Required to deploy to GitHub Pages. | |
| id-token: write # WHY: Required by deploy-pages for OIDC authentication. | |
| concurrency: | |
| group: github-pages | |
| cancel-in-progress: false | |
| # WHY: GitHub Pages is a shared deployment target. | |
| # OBS: Do not cancel an in-progress Pages deployment with another deployment. | |
| env: | |
| PYTHONUNBUFFERED: "1" # WHY: Real-time log output in CI. | |
| PYTHONIOENCODING: "utf-8" # WHY: Consistent encoding across platforms. | |
| UV_FROZEN: "1" # WHY: Deployment MUST use uv.lock without updating it. | |
| jobs: | |
| docs: | |
| name: Deploy Documentation site | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 30 # WHY: Fail fast if a step hangs unexpectedly. | |
| steps: | |
| # ============================================================ | |
| # A) ASSEMBLE: Checkout code and set up environment | |
| # ============================================================ | |
| - name: A1) Checkout repository code | |
| uses: actions/checkout@v7 | |
| # WHY: Required so all subsequent steps can access repo files. | |
| - name: A2) Configure GitHub Pages | |
| uses: actions/configure-pages@v6 | |
| # WHY: Sets Pages metadata used by upload-pages-artifact and deploy-pages. | |
| # OBS: Must run before the build step so base URL is available if needed. | |
| - name: A3) Install uv (with caching) | |
| uses: astral-sh/setup-uv@v10.0.1 | |
| with: | |
| enable-cache: true | |
| cache-dependency-glob: "uv.lock" | |
| # WHY: Invalidate dependency cache when the committed lockfile changes. | |
| - name: A4) Install project Python | |
| run: uv python install | |
| # WHY: Ensures the Python version declared in .python-version is available. | |
| # OBS: uv manages the interpreter locally in the CI environment. | |
| - name: A5) Install dependencies from committed lockfile | |
| run: uv sync --frozen | |
| # WHY: Install all configured dependency groups from uv.lock. | |
| # REQ: Deployment MUST fail rather than update a stale lockfile. | |
| - name: A6) Show tool versions | |
| run: | | |
| uv --version | |
| uv run python --version | |
| if [ -f "zensical.toml" ]; then | |
| uv run python -m zensical --version | |
| fi | |
| # WHY: Version output makes deployment logs easier to debug when tools change. | |
| # ============================================================ | |
| # D) DEPLOY: Build and publish docs | |
| # ============================================================ | |
| - name: D1) Build docs with Zensical | |
| run: | | |
| if [ ! -f "zensical.toml" ]; then | |
| echo "zensical.toml not found; refusing to deploy." >> "$GITHUB_STEP_SUMMARY" | |
| exit 1 | |
| fi | |
| uv run python -m zensical build | |
| # WHY: Hard-fail if zensical.toml is missing rather than deploying nothing. | |
| # OBS: In CI (ci-python-zensical.yml) the missing config is a soft skip. | |
| # Here it is a hard failure because a deploy without docs is wrong. | |
| - name: D2) Verify site output exists | |
| run: | | |
| if [ ! -d "site" ]; then | |
| echo "## Documentation build output missing" >> "$GITHUB_STEP_SUMMARY" | |
| echo "Expected directory 'site/' was not created." >> "$GITHUB_STEP_SUMMARY" | |
| echo "Check the Zensical build step and zensical.toml configuration." >> "$GITHUB_STEP_SUMMARY" | |
| exit 1 | |
| fi | |
| # WHY: Catch a silent build failure before attempting to upload an empty artifact. | |
| # OBS: Zensical outputs to site/ by default; update this path if zensical.toml | |
| # configures a different output directory. | |
| - name: D3) Upload Pages artifact | |
| uses: actions/upload-pages-artifact@v5 | |
| with: | |
| path: site | |
| # WHY: Packages the built static site for the deploy-pages action. | |
| # OBS: path must match the output directory verified in D2. | |
| - name: D4) Deploy to GitHub Pages | |
| uses: actions/deploy-pages@v5 | |
| # WHY: Publishes the uploaded artifact to GitHub Pages. | |
| # OBS: Requires pages: write and id-token: write permissions (set above). | |
| # OBS: The deployed URL is shown in the Actions log after this step completes. |