dartdoc-gh-pages.yml

# =============================================================================
# Dartdoc Deployment Workflow
# =============================================================================
#
# This workflow generates API documentation using Dartdoc for the ouds_core
# package and deploys it to GitHub Pages.
#
# 🌐 Production URL: https://flutter.unified-design-system.orange.com/
# 🔍 PR Preview URL:  https://flutter.unified-design-system.orange.com/prPreview/<PR_NUMBER>/
#
# Architecture:
# - Branch: gh-pages
# - Folder: /docs (configured in GitHub Pages settings)
# - Custom domain: flutter.unified-design-system.orange.com (via CNAME)
#
# Jobs overview:
# ┌─────────────────┬────────────────────────────────────────────────────────┐
# │ Job             │ Description                                            │
# ├─────────────────┼────────────────────────────────────────────────────────┤
# │ build           │ Generates dartdoc and uploads as artifact              │
# │ deploy          │ Deploys to production (push/dispatch only)             │
# │ deploy-preview  │ Deploys PR preview to /prPreview/<number>/            │
# │ cleanup-preview │ Removes PR preview when PR is closed/merged            │
# └─────────────────┴────────────────────────────────────────────────────────┘
#
# Trigger matrix:
# ┌─────────────────────┬───────┬────────┬────────────────┬─────────────────┐
# │ Event               │ build │ deploy │ deploy-preview │ cleanup-preview │
# ├─────────────────────┼───────┼────────┼────────────────┼─────────────────┤
# │ push main/develop   │  ✅   │   ✅   │       ❌       │       ❌        │
# │ workflow_dispatch    │  ✅   │   ✅   │       ❌       │       ❌        │
# │ PR opened/sync      │  ✅   │   ❌   │       ✅       │       ❌        │
# │ PR closed/merged    │  ❌   │   ❌   │       ❌       │       ✅        │
# └─────────────────────┴───────┴────────┴────────────────┴─────────────────┘
# =============================================================================

name: Deploy Dartdoc with GitHub Pages dependencies preinstalled

# -----------------------------------------------------------------------------
# Triggers
# -----------------------------------------------------------------------------
on:
  # Deploy production docs when code is pushed to main or develop
  push:
    branches:
      - main
      - develop

  # Allow manual trigger from GitHub Actions UI
  workflow_dispatch:

  # Handle pull requests for preview deployments and cleanup
  pull_request:
    types:
      - opened       # New PR → deploy preview
      - synchronize  # New commits pushed → update preview
      - closed       # PR merged/closed → cleanup preview

permissions:
  read-all

# -----------------------------------------------------------------------------
# Concurrency
# -----------------------------------------------------------------------------
# Each PR gets its own concurrency group to avoid conflicts.
# Push events use the git ref as group key.
# cancel-in-progress ensures only the latest build runs for each PR.
concurrency:
  group: "pages-${{ github.event.pull_request.number || github.ref }}"
  cancel-in-progress: true

jobs:
  # ===========================================================================
  # JOB: build
  # ===========================================================================
  # Generates the Dartdoc documentation from ouds_core and uploads it as an
  # artifact. Runs for all events EXCEPT when a PR is closed (no need to
  # rebuild docs just to clean up).
  # ===========================================================================
  build:
    if: github.event.action != 'closed'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write

    steps:
      - name: Checkout
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          submodules: recursive

      - name: Setup Dart
        uses: dart-lang/setup-dart@e51d8e571e22473a2ddebf0ef8a2123f0ab2c02c # v1.7.1
        with:
          sdk: stable

      - name: Setup environment
        uses: ./.github/actions/setup

      - name: Setup Pages
        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0

      - name: Setup Ruby
        uses: ruby/setup-ruby@a6e6f86333f0a2523ece813039b8b4be04560854 # v1.190.0
        with:
          ruby-version: 3.3.4

      # Generate API documentation from ouds_core package
      - name: Build with Dartdoc
        run: |
          cd ouds_core
          dart pub get
          dart doc .

      # Move generated docs to a clean directory for upload
      - name: Move DartDoc output
        run: |
          mkdir -p ./docs
          mv ouds_core/doc/api/* ./docs

      # Include branding assets in the documentation
      - name: Copy images files (orange logo and banner)
        run: |
          mkdir -p ./docs/assets
          cp ouds_core/assets/doc/orange_logo.svg ./docs/assets/
          cp ouds_core/assets/doc/banner.png ./docs/assets/

      # Upload as GitHub Pages artifact (creates a tar archive named "github-pages")
      - name: Upload artifact
        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
        with:
          path: ./docs

  # ===========================================================================
  # JOB: deploy
  # ===========================================================================
  # Deploys the documentation to the PRODUCTION site.
  # Only runs on push to main/develop or manual workflow_dispatch.
  # Never runs on pull_request events.
  #
  # Deployment target:
  #   Branch: gh-pages
  #   Folder: docs/
  #   URL: https://flutter.unified-design-system.orange.com/
  #
  # Important: Preserves the prPreview/ subdirectory so that active PR
  # previews are not destroyed by a production deployment.
  # ===========================================================================
  deploy:
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    needs: build
    permissions:
      contents: write
      pages: write
      id-token: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Download artifact
        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
        with:
          name: github-pages

      - name: Extract artifact into temporary directory
        run: |
          mkdir -p /tmp/docs-output
          tar -xvf artifact.tar -C /tmp/docs-output
          ls -la /tmp/docs-output

      - name: Commit changes and push to gh-pages
        run: |
          git config --global user.name "GitHub Actions"
          git config --global user.email "actions@github.com"
          git fetch origin gh-pages || true
          git checkout gh-pages || git checkout --orphan gh-pages

          # Backup prPreview/ so active PR previews survive the deploy
          if [ -d "docs/prPreview" ]; then
            cp -r docs/prPreview /tmp/prPreview-backup
          fi

          # Clean everything and replace with new docs
          git rm -rf . || true
          git clean -fd || true
          mkdir -p docs
          cp -r /tmp/docs-output/* docs/

          # Restore PR previews
          if [ -d "/tmp/prPreview-backup" ]; then
            cp -r /tmp/prPreview-backup docs/prPreview
          fi

          # CNAME file is required for custom domain resolution
          echo "flutter.unified-design-system.orange.com" > docs/CNAME

          git add docs/
          commit_message="doc: deploy site to GitHub Pages - Version $(date +%Y%m%d)"
          git commit -m "$commit_message" || echo "No changes to commit"
          git push origin gh-pages --force
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  # ===========================================================================
  # JOB: deploy-preview
  # ===========================================================================
  # Deploys a PR-specific preview of the documentation to a unique URL.
  # This allows reviewers to check documentation changes before merging.
  #
  # Preview URL pattern:
  #   https://flutter.unified-design-system.orange.com/prPreview/<PR_NUMBER>/
  #
  # Example for PR #707:
  #   https://flutter.unified-design-system.orange.com/prPreview/707/
  #
  # A comment is automatically posted/updated on the PR with the preview link.
  # ===========================================================================
  deploy-preview:
    if: github.event_name == 'pull_request' && github.event.action != 'closed'
    runs-on: ubuntu-latest
    needs: build
    permissions:
      contents: write
      pull-requests: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Download artifact
        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
        with:
          name: github-pages

      - name: Extract artifact
        run: |
          mkdir -p /tmp/docs-output
          tar -xvf artifact.tar -C /tmp/docs-output

      - name: Deploy PR preview to gh-pages
        run: |
          git config --global user.name "GitHub Actions"
          git config --global user.email "actions@github.com"
          git fetch origin gh-pages || true
          git checkout gh-pages || git checkout --orphan gh-pages

          # Remove old preview for this PR (if updating after new commits)
          rm -rf docs/prPreview/${{ github.event.pull_request.number }}

          # Deploy new preview to docs/prPreview/<PR_NUMBER>/
          mkdir -p docs/prPreview/${{ github.event.pull_request.number }}
          cp -r /tmp/docs-output/* docs/prPreview/${{ github.event.pull_request.number }}/
          git add docs/prPreview/${{ github.event.pull_request.number }}/
          git commit -m "doc: deploy PR #${{ github.event.pull_request.number }} preview" || echo "No changes to commit"
          git push origin gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      # Post or update a comment on the PR with the preview URL
      - name: Comment PR with preview URL
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
        with:
          script: |
            const prNumber = context.payload.pull_request.number;
            const previewUrl = `https://flutter.unified-design-system.orange.com/prPreview/${prNumber}/`;
            const body = `📖 **Documentation preview deployed!**\n\n🔗 ${previewUrl}`;

            // Check if a preview comment already exists (avoid duplicate comments)
            const comments = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: prNumber,
            });
            const existing = comments.data.find(c => c.body.includes('Documentation preview deployed'));
            if (existing) {
              // Update existing comment
              await github.rest.issues.updateComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                comment_id: existing.id,
                body: body,
              });
            } else {
              // Create new comment
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: prNumber,
                body: body,
              });
            }

  # ===========================================================================
  # JOB: cleanup-preview
  # ===========================================================================
  # Removes the PR preview directory when the PR is closed or merged.
  # This keeps the gh-pages branch clean and avoids accumulating stale previews.
  # ===========================================================================
  cleanup-preview:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Remove PR preview
        run: |
          git config --global user.name "GitHub Actions"
          git config --global user.email "actions@github.com"
          git fetch origin gh-pages || true
          git checkout gh-pages || true

          # Only remove if the preview directory exists
          if [ -d "docs/prPreview/${{ github.event.pull_request.number }}" ]; then
            rm -rf docs/prPreview/${{ github.event.pull_request.number }}
            git add -A
            git commit -m "doc: remove PR #${{ github.event.pull_request.number }} preview" || echo "No changes to commit"
            git push origin gh-pages
          fi
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}