docs.yml

---
name: Docs
on:
  push:
    branches: [main, 'v[0-9]+.[0-9]+.[0-9]+*']
    paths:
      - docs/**
      - src/**
      - pyproject.toml
      - uv.lock
      - .github/workflows/docs.yml
      - scripts/docs.py
      - zensical.toml
      - CHANGELOG.md
  pull_request:
    branches: [main, 'v[0-9]+.[0-9]+.[0-9]+*']
    paths:
      - docs/**
      - src/**
      - pyproject.toml
      - uv.lock
      - .github/workflows/docs.yml
      - scripts/docs.py
      - zensical.toml
      - CHANGELOG.md
  workflow_dispatch:
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
env:
  # renovate: datasource=python-version depName=python
  PYTHON_VERSION: 3.13.11
  ARTIFACT_RETENTION_DAYS: 7
jobs:
  changes:
    name: File Detection
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      docs: ${{ steps.docs_changes.outputs.any_changed }}
      code: ${{ steps.code_changes.outputs.any_changed }}
      any: ${{ steps.docs_changes.outputs.any_changed == 'true' || steps.code_changes.outputs.any_changed == 'true' }}
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6
        with:
          fetch-depth: 0
      - name: Check Docs
        uses: tj-actions/changed-files@24d32ffd492484c1d75e0c0b894501ddb9d30d62  # v47
        id: docs_changes
        with:
          files: |
            docs/**
            zensical.toml
            scripts/docs.py
            .github/workflows/docs.yml
            CHANGELOG.md
      - name: Check Code
        uses: tj-actions/changed-files@24d32ffd492484c1d75e0c0b894501ddb9d30d62  # v47
        id: code_changes
        with:
          files: |
            src/**
            pyproject.toml
            uv.lock
  build:
    name: Build
    runs-on: ubuntu-latest
    needs: [changes]
    if: needs.changes.outputs.any || github.event_name == 'workflow_dispatch'
    permissions:
      contents: read
      pull-requests: write
    outputs:
      any: ${{ needs.changes.outputs.any }}
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6
        with:
          fetch-depth: 0
          sparse-checkout: |
            docs
            src
            scripts
            .github/actions
            .github/workflows
            .github/scripts
            zensical.toml
            pyproject.toml
            uv.lock
      - name: Setup Python
        uses: ./.github/actions/setup-python
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          enable-cache: true
      - name: Install Dependencies
        run: |
          echo "Installing documentation dependencies..."
          uv sync
      - name: Build Zensical Documentation
        run: |
          echo "Building Zensical documentation..."
          uv run zensical build
          echo "Documentation build completed successfully"
      - name: Upload Documentation Artifact
        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f  # v6
        with:
          name: docs
          path: site
          retention-days: ${{ env.ARTIFACT_RETENTION_DAYS }}
          if-no-files-found: warn

      # Optimize cache for CI: Remove pre-built wheels, keep source-built wheels
      # This improves cache efficiency by only keeping wheels that take time to build
      # Docs: https://docs.astral.sh/uv/concepts/cache/#caching-in-continuous-integration
      - name: Prune uv cache for CI
        if: always()
        run: uv cache prune --ci
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    needs: [build]
    if: (github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref,
      'refs/heads/v'))) || github.event_name == 'pull_request' || github.event_name
      == 'workflow_dispatch'
    permissions:
      contents: read
      deployments: write
      pull-requests: write
      issues: write
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6
      - name: Download Documentation Artifact
        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131  # v7
        with:
          name: docs
          path: site
      # Deploy to Cloudflare (requires Cloudflare API)
      # Note: These steps require Cloudflare API access and won't work with act (local testing)
      # They will fail gracefully in act, allowing manual testing of docs build steps
      - name: Ensure Wrangler v4 is available
        run: npx wrangler@4 --version
      - name: Deploy to Production
        if: github.ref == 'refs/heads/main'
        id: production_deploy
        uses: mkcode/wrangler-version-deploy-action-with-metadata@35ee741c298be6c3bb124fbeef5feb85dabe3fcc  # v1
        continue-on-error: true
        with:
          api_token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          wrangler_command: npx wrangler@4
          config: wrangler.toml
          upload_args: --env production
          deploy_args: --env production
          message_template: 'Production: {{repo}}@{{short_sha}} on {{branch}} by {{actor}}
            (run {{run_number}})'
      - name: Upload Preview Version
        if: github.ref != 'refs/heads/main' || github.event_name == 'pull_request'
        id: preview_upload
        run: |
          # Check if Cloudflare API token is available
          if [ -z "$CLOUDFLARE_API_TOKEN" ]; then
            echo "⚠️ CLOUDFLARE_API_TOKEN not available - skipping preview deployment" >> "$GITHUB_STEP_SUMMARY"
            echo "preview_url=🚀 Preview deployment skipped (no Cloudflare API token)" >> "$GITHUB_OUTPUT"
            echo "version_id=skipped" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          # Debug: Check if site directory exists
          {
            echo "Checking site directory..."
            if [ -d "site" ]; then
              find site -maxdepth 1 -type f -o -type d | head -20
            else
              echo "Site directory not found at site"
            fi
          } >> "$GITHUB_STEP_SUMMARY"

          # Run wrangler upload directly to capture the preview URL
          UPLOAD_OUTPUT=$(npx wrangler@4 versions upload --config wrangler.toml --env preview --message="Preview: tux@${{ github.sha }}" 2>&1)
          UPLOAD_EXIT_CODE=$?

          # Echo the output for debugging and set outputs
          {
            echo "Upload output:"
            echo "$UPLOAD_OUTPUT"
            echo "Exit code: $UPLOAD_EXIT_CODE"

            # If upload failed, log error
            if [ $UPLOAD_EXIT_CODE -ne 0 ]; then
              echo "❌ Wrangler upload failed with exit code $UPLOAD_EXIT_CODE"
            fi
          } >> "$GITHUB_STEP_SUMMARY"

          # If upload failed, exit with error
          if [ $UPLOAD_EXIT_CODE -ne 0 ]; then
            echo "$UPLOAD_OUTPUT" >&2
            exit $UPLOAD_EXIT_CODE
          fi

          # Extract version ID
          VERSION_ID=$(echo "$UPLOAD_OUTPUT" | grep "Worker Version ID:" | sed 's/.*Worker Version ID: //' | tr -d '\n')

          # Extract preview URL from upload output
          PREVIEW_URL=$(echo "$UPLOAD_OUTPUT" | grep "Version Preview URL:" | sed 's/.*Version Preview URL: //' | tr -d '\n')

          # Set outputs and log results
          {
            if [ -n "$VERSION_ID" ]; then
              echo "version_id=$VERSION_ID" >> "$GITHUB_OUTPUT"
              echo "✅ Found version ID: $VERSION_ID"
            else
              echo "❌ No version ID found in upload output"
            fi
            if [ -n "$PREVIEW_URL" ]; then
              echo "preview_url=$PREVIEW_URL" >> "$GITHUB_OUTPUT"
              echo "✅ Found preview URL: $PREVIEW_URL"
            else
              echo "⚠️ No preview URL found in upload output"
            fi
          } >> "$GITHUB_STEP_SUMMARY"
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
      - name: Deploy Preview Version
        if: github.ref != 'refs/heads/main' || github.event_name == 'pull_request'
        id: preview_deploy
        run: |
          # Skip deployment if upload was skipped due to missing token
          if [ "${{ steps.preview_upload.outputs.version_id }}" = "skipped" ]; then
            echo "⚠️ Skipping preview deployment - no Cloudflare API token available" >> "$GITHUB_STEP_SUMMARY"
            exit 0
          fi

          # Deploy the uploaded version
          npx wrangler@4 versions deploy "${{ steps.preview_upload.outputs.version_id }}" -y --config wrangler.toml --env preview --message="Preview: tux@${{ github.sha }} on ${{ github.ref_name }} by ${{ github.actor }} (run ${{ github.run_number }})"
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
      - name: Find Pull Request
        if: github.event_name == 'push'
        uses: juliangruber/find-pull-request-action@48b6133aa6c826f267ebd33aa2d29470f9d9e7d0  # v1
        id: find_pr
        with:
          branch: ${{ github.ref_name }}
          state: open
      - name: Find Documentation Comment
        if: github.event_name == 'pull_request' || steps.find_pr.outputs.number !=
          ''
        uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad  # v4
        id: find_comment
        with:
          issue-number: ${{ github.event.pull_request.number || steps.find_pr.outputs.number }}
          comment-author: github-actions[bot]
          body-includes: '## 📚 Documentation Preview'
      - name: Prepare Preview URL
        if: github.event_name == 'pull_request' || steps.find_pr.outputs.number !=
          ''
        id: prepare_url
        run: |
          if [ "${{ steps.preview_upload.outputs.version_id }}" = "skipped" ]; then
            echo "preview_url=🚀 Preview deployment skipped (no Cloudflare API token)" >> "$GITHUB_OUTPUT"
            echo "is_url=false" >> "$GITHUB_OUTPUT"
            echo "⚠️ Preview deployment skipped due to missing Cloudflare API token" >> "$GITHUB_STEP_SUMMARY"
          elif [ -n "${{ steps.preview_upload.outputs.preview_url }}" ]; then
            echo "preview_url=${{ steps.preview_upload.outputs.preview_url }}" >> "$GITHUB_OUTPUT"
            echo "is_url=true" >> "$GITHUB_OUTPUT"
            echo "✅ Using preview URL from wrangler upload output" >> "$GITHUB_STEP_SUMMARY"
          else
            echo "preview_url=🚀 Preview deployed successfully" >> "$GITHUB_OUTPUT"
            echo "is_url=false" >> "$GITHUB_OUTPUT"
            echo "Preview deployment completed successfully" >> "$GITHUB_STEP_SUMMARY"
          fi
      - name: Create or Update Comment
        if: github.event_name == 'pull_request' || steps.find_pr.outputs.number !=
          ''
        uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9  # v5
        continue-on-error: true
        with:
          comment-id: ${{ steps.find_comment.outputs.comment-id }}
          issue-number: ${{ github.event.pull_request.number || steps.find_pr.outputs.number }}
          edit-mode: replace
          body: |-
            ## 📚 Documentation Preview
            | Type | URL | Version | Message |
            |------|-----|---------|---------|
            | Production | [https://tux.atl.dev](https://tux.atl.dev) | - | - |
            | Preview | ${{ steps.prepare_url.outputs.is_url == 'true' && format('[{0}]({0})', steps.prepare_url.outputs.preview_url) || steps.prepare_url.outputs.preview_url }} | ${{ steps.preview_upload.outputs.version_id || '-' }} | Preview: tux@${{ github.sha }} on ${{ github.ref_name }} by ${{ github.actor }} (run ${{ github.run_number }}) |