docs-deploy.yml

name: "Docs - Deploy"

on:
  push:
    branches: [ main ]
    paths:
      - 'docs/**'
      - 'samples/SkiaSharpDemo.Blazor/**'
      - 'source/**'
      - 'scripts/**'
      - '.github/workflows/docs-deploy.yml'
  pull_request:
    branches: [ main ]
    paths:
      - 'docs/**'
      - 'samples/SkiaSharpDemo.Blazor/**'
      - 'source/**'
      - 'scripts/**'
      - '.github/workflows/docs-deploy.yml'
    types: [ opened, synchronize, reopened ]
  workflow_dispatch:

# Default to no permissions — each job declares only what it needs.
permissions: {}

# Ensure documentation workflows run sequentially
concurrency:
  group: "docs-deployment"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read   # checkout only
    outputs:
      artifact_name: ${{ steps.vars.outputs.artifact_name }}
      is_staging: ${{ steps.vars.outputs.is_staging }}
      pr_number: ${{ steps.vars.outputs.pr_number }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup build variables
        id: vars
        env:
          EVENT_NAME: ${{ github.event_name }}
          PR_NUMBER: ${{ github.event.number }}
        shell: bash
        run: |
          if [ "$EVENT_NAME" == "pull_request" ]; then
            # Validate PR_NUMBER is a positive integer before using it in artifact names/paths
            if ! [[ "$PR_NUMBER" =~ ^[1-9][0-9]*$ ]]; then
              echo "Invalid PR number: $PR_NUMBER"
              exit 1
            fi
            echo "artifact_name=staging-site-${PR_NUMBER}" >> $GITHUB_OUTPUT
            echo "sample_base_href=/SkiaSharp.Extended/staging/${PR_NUMBER}/sample/" >> $GITHUB_OUTPUT
            echo "sample_segment_count=4" >> $GITHUB_OUTPUT
            echo "is_staging=true" >> $GITHUB_OUTPUT
            echo "pr_number=${PR_NUMBER}" >> $GITHUB_OUTPUT
            echo "source_label=PR #${PR_NUMBER}" >> $GITHUB_OUTPUT
          else
            echo "artifact_name=main-site" >> $GITHUB_OUTPUT
            echo "sample_base_href=/SkiaSharp.Extended/sample/" >> $GITHUB_OUTPUT
            echo "sample_segment_count=2" >> $GITHUB_OUTPUT
            echo "is_staging=false" >> $GITHUB_OUTPUT
            echo "pr_number=" >> $GITHUB_OUTPUT
            echo "source_label=main" >> $GITHUB_OUTPUT
          fi

      - name: Install MAUI workload
        run: dotnet workload install maui-android

      - name: Install wasm-tools workload
        run: dotnet workload install wasm-tools

      - name: Restore .NET tools
        run: dotnet tool restore

      - name: Build the assemblies
        run: dotnet build scripts/SkiaSharp.Extended-Pack.slnf -c Release -f net10.0

      - name: Publish Blazor sample
        env:
          SOURCE_LABEL: ${{ steps.vars.outputs.source_label }}
        run: |
          COMMIT_SHORT="${GITHUB_SHA:0:7}"
          BUILD_INFO="${SOURCE_LABEL} · ${COMMIT_SHORT}"
          dotnet publish samples/SkiaSharpDemo.Blazor/SkiaSharpDemo.Blazor.csproj \
            -c Release -o publish/sample \
            -p:BuildInfo="$BUILD_INFO"

      - name: Build docs
        env:
          SOURCE_LABEL: ${{ steps.vars.outputs.source_label }}
        run: |
          COMMIT_SHORT="${GITHUB_SHA:0:7}"
          APP_FOOTER="source: ${SOURCE_LABEL} · ${COMMIT_SHORT}"
          jq --arg footer "$APP_FOOTER" \
            '.build.globalMetadata._appFooter = $footer' \
            docs/docfx.json > docs/docfx-build.json
          dotnet docfx docs/docfx-build.json

      - name: Copy Blazor sample into docs site
        env:
          BASE_HREF: ${{ steps.vars.outputs.sample_base_href }}
          SEGMENT_COUNT: ${{ steps.vars.outputs.sample_segment_count }}
        run: |
          mkdir -p docs/_site/sample
          cp -r publish/sample/wwwroot/. docs/_site/sample/

          # Disable Jekyll processing so _framework directory is served
          touch docs/_site/.nojekyll

          # Rewrite base href for deployment
          sed -i "s|<base href=\"/\" />|<base href=\"$BASE_HREF\" />|" docs/_site/sample/index.html

          # Update segmentCount in 404.html
          if [ -f docs/_site/sample/404.html ]; then
            sed -i "s|var segmentCount = [0-9]*;|var segmentCount = $SEGMENT_COUNT;|" docs/_site/sample/404.html
          fi

      - name: Upload site artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ steps.vars.outputs.artifact_name }}
          path: docs/_site
          retention-days: 1

  deploy:
    runs-on: ubuntu-latest
    needs: build
    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
    permissions:
      contents: write
    steps:
      - name: Checkout gh-pages branch
        uses: actions/checkout@v4
        with:
          ref: gh-pages
          fetch-depth: 0

      - name: Download site artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ needs.build.outputs.artifact_name }}
          path: /tmp/site-temp

      - name: Setup main site content
        if: needs.build.outputs.is_staging == 'false'
        run: |
          find . -maxdepth 1 \
              -not -name 'staging' \
              -not -name '.git' \
              -not -name '.' \
              -not -name '..' \
            -exec rm -rf {} \;
          cp -r /tmp/site-temp/. .
          rm -rf /tmp/site-temp
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add .
          if ! git diff --cached --quiet; then
            git commit -m "Deploy main documentation from commit ${{ github.sha }}"
            git push origin gh-pages
          else
            echo "No changes to commit"
          fi

      - name: Setup staging site content
        if: needs.build.outputs.is_staging == 'true'
        env:
          PR_NUMBER: ${{ needs.build.outputs.pr_number }}
        run: |
          # Validate PR_NUMBER is a positive integer before using in paths
          if ! [[ "$PR_NUMBER" =~ ^[1-9][0-9]*$ ]]; then
            echo "Invalid PR number: $PR_NUMBER"
            exit 1
          fi
          mkdir -p staging/$PR_NUMBER
          rm -rf staging/$PR_NUMBER/*
          cp -r /tmp/site-temp/. staging/$PR_NUMBER/
          rm -rf /tmp/site-temp

          # Ensure .nojekyll exists at root so _framework is served
          touch .nojekyll

          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add .nojekyll staging/$PR_NUMBER
          if ! git diff --cached --quiet; then
            git commit -m "Deploy staging docs for PR #$PR_NUMBER"
            git push origin gh-pages
          else
            echo "No changes to commit"
          fi

  comment:
    runs-on: ubuntu-latest
    needs: [build, deploy]
    if: needs.build.outputs.is_staging == 'true' && (github.event.action == 'opened' || github.event.action == 'reopened')
    permissions:
      pull-requests: write
    steps:
      - name: Comment on PR
        uses: actions/github-script@v7
        with:
          script: |
            const prNumber = context.issue.number;
            const stagingUrl = `https://mono.github.io/SkiaSharp.Extended/staging/${prNumber}/`;
            const sampleUrl = `https://mono.github.io/SkiaSharp.Extended/staging/${prNumber}/sample/`;

            // Only comment once; check for an existing bot comment to avoid duplicates on reopen
            const comments = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: prNumber
            });
            const botComment = comments.data.find(c =>
              c.user.type === 'Bot' &&
              c.body.includes('Documentation Preview')
            );
            if (botComment) {
              console.log('Bot comment already exists, skipping.');
              return;
            }

            const commentBody = [
              '📖 **Documentation Preview**',
              '',
              'The documentation for this PR has been deployed and is available at:',
              '',
              `🔗 **[View Staging Documentation](${stagingUrl})**`,
              '',
              `🔗 **[View Staging Blazor Sample](${sampleUrl})**`,
              '',
              'This preview will be updated automatically when you push new commits to this PR.',
              '',
              '---',
              '*This comment is automatically updated by the documentation staging workflow.*'
            ].join('\n');

            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: prNumber,
              body: commentBody
            });