deploy.yml

name: Deploy Documentation

on:
  push:
    branches:
      - main
      - dev
    tags:
      - 'v*'
  delete:
    # Trigger when branches are deleted
  workflow_dispatch:
    inputs:
      cleanup_version:
        description: 'Versions to cleanup, comma-separated (e.g. "dev,feat-foo,0.2.1")'
        required: false
        type: string

permissions:
  contents: write
  pages: write
  id-token: write

concurrency:
  group: deploy-docs
  cancel-in-progress: false

jobs:
  determine-version:
    name: Determine Version & Environment
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.version.outputs.version }}
      safe_version: ${{ steps.version.outputs.safe_version }}
      alias: ${{ steps.version.outputs.alias }}
      environment: ${{ steps.version.outputs.environment }}
      should_deploy: ${{ steps.version.outputs.should_deploy }}
      is_dev: ${{ steps.version.outputs.is_dev }}
      warning_message: ${{ steps.version.outputs.warning_message }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Determine version and environment
        id: version
        run: |
          # On delete events, only the cleanup job should run
          if [[ "${{ github.event_name }}" == "delete" ]]; then
            echo "Delete event — skipping deploy (cleanup job handles this)"
            echo "should_deploy=false" >> $GITHUB_OUTPUT
            exit 0
          fi

          REF_NAME="${{ github.ref_name }}"
          REF_TYPE="${{ github.ref_type }}"

          echo "Debug: REF_NAME=$REF_NAME, REF_TYPE=$REF_TYPE"

          VERSION=""
          ALIAS=""
          ENVIRONMENT=""
          IS_DEV="false"
          WARNING_MESSAGE=""

          if [[ "$REF_TYPE" == "tag" ]] && [[ "$REF_NAME" == v* ]]; then
            VERSION="${REF_NAME#v}"

            # Only deploy docs for final releases (skip dev, alpha, beta, rc, post)
            if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
              echo "Skipping pre-release version: $VERSION"
              echo "should_deploy=false" >> $GITHUB_OUTPUT
              exit 0
            fi

            ALIAS="latest"
            ENVIRONMENT="production"
            IS_DEV="false"
            WARNING_MESSAGE=""
          elif [[ "$REF_NAME" == "main" ]]; then
            VERSION="main"
            ALIAS="stable"
            ENVIRONMENT="production"
            IS_DEV="false"
            WARNING_MESSAGE="⚠️ This is the development version of the documentation for the main branch."
          elif [[ "$REF_NAME" == "dev" ]]; then
            VERSION="dev"
            ALIAS="development"
            ENVIRONMENT="staging"
            IS_DEV="true"
            WARNING_MESSAGE="⚠️ This is the development version of the documentation. Features may change."
          else
            echo "Skipping unrecognized ref: $REF_NAME"
            echo "should_deploy=false" >> $GITHUB_OUTPUT
            exit 0
          fi

          SAFE_VERSION="${VERSION//\//-}"

          echo "safe_version=$SAFE_VERSION" >> $GITHUB_OUTPUT
          echo "version=$VERSION" >> $GITHUB_OUTPUT
          echo "alias=$ALIAS" >> $GITHUB_OUTPUT
          echo "environment=$ENVIRONMENT" >> $GITHUB_OUTPUT
          echo "is_dev=$IS_DEV" >> $GITHUB_OUTPUT
          echo "warning_message=$WARNING_MESSAGE" >> $GITHUB_OUTPUT
          echo "should_deploy=true" >> $GITHUB_OUTPUT

          echo "Version: $VERSION"
          echo " Alias: $ALIAS"
          echo "Environment: $ENVIRONMENT"
          echo " Is Dev: $IS_DEV"

  deploy:
    name: Deploy Documentation
    needs: [determine-version]
    if: needs.determine-version.outputs.should_deploy == 'true'
    runs-on: ubuntu-latest
    environment:
      name: ${{ needs.determine-version.outputs.environment }}
      url: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.10'

      - name: Install uv
        uses: astral-sh/setup-uv@v6
        with:
          enable-cache: true

      - name: Install project and dependencies
        run: uv sync --group docs

      - name: Configure Git
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Deploy with mike
        run: |
          uv run mike deploy \
            --update-aliases \
            ${{ needs.determine-version.outputs.safe_version }} \
            ${{ needs.determine-version.outputs.alias }}
          uv run mike set-default stable
          git push origin gh-pages

      - name: Deployment Summary
        run: |
          echo "## 📚 Documentation Deployment Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "| Property | Value |" >> $GITHUB_STEP_SUMMARY
          echo "|----------|-------|" >> $GITHUB_STEP_SUMMARY
          echo "| Version | ${{ needs.determine-version.outputs.version }} |" >> $GITHUB_STEP_SUMMARY
          echo "| Alias | ${{ needs.determine-version.outputs.alias }} |" >> $GITHUB_STEP_SUMMARY
          echo "| Environment | ${{ needs.determine-version.outputs.environment }} |" >> $GITHUB_STEP_SUMMARY
          echo "| Branch/Tag | ${{ github.ref_name }} |" >> $GITHUB_STEP_SUMMARY
          echo "| Commit | ${{ github.sha }} |" >> $GITHUB_STEP_SUMMARY
          if [[ "${{ needs.determine-version.outputs.is_dev }}" == "true" ]]; then
            echo "| Warning | ⚠️ Development version |" >> $GITHUB_STEP_SUMMARY
          fi
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "✅ Documentation deployed successfully!"
          echo "📖 View at: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}"

  cleanup:
    name: Cleanup Documentation Version
    runs-on: ubuntu-latest
    if: github.event_name == 'delete' || github.event.inputs.cleanup_version != ''
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
          ref: gh-pages
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.10'

      - name: Install uv
        run: pip install uv

      - name: Install mike
        run: uv pip install mike --system

      - name: Configure Git
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Create mkdocs stub for mike
        run: |
          cat > mkdocs.yml << 'EOF'
          site_name: digitalkin
          docs_dir: .mike_stub_docs
          EOF
          mkdir -p .mike_stub_docs

      - name: Determine versions to cleanup
        id: cleanup_version
        run: |
          VERSIONS=""

          if [[ "${{ github.event_name }}" == "delete" ]]; then
            REF_NAME="${{ github.event.ref }}"
            REF_TYPE="${{ github.event.ref_type }}"

            echo "Deleted ref: $REF_NAME (type: $REF_TYPE)"

            if [[ "$REF_TYPE" == "branch" ]]; then
              SAFE_VERSION="${REF_NAME//\//-}"

              if [[ "$REF_NAME" != "main" ]] && [[ "$REF_NAME" != "dev" ]]; then
                VERSIONS="$SAFE_VERSION"
              else
                echo "Skipping cleanup for protected branch: $REF_NAME"
              fi
            else
              echo "Not a branch deletion, skipping"
            fi
          elif [[ "${{ github.event.inputs.cleanup_version }}" != "" ]]; then
            # Manual cleanup — comma-separated list supported
            RAW="${{ github.event.inputs.cleanup_version }}"
            # Normalize: trim spaces around commas, replace / with -
            VERSIONS=$(echo "$RAW" | tr ',' '\n' | sed 's/^ *//;s/ *$//' | sed 's|/|-|g' | paste -sd ',' -)
          fi

          if [[ -n "$VERSIONS" ]]; then
            echo "versions=$VERSIONS" >> $GITHUB_OUTPUT
            echo "should_cleanup=true" >> $GITHUB_OUTPUT
            echo "Versions to cleanup: $VERSIONS"
          else
            echo "should_cleanup=false" >> $GITHUB_OUTPUT
          fi

      - name: Delete documentation versions
        if: steps.cleanup_version.outputs.should_cleanup == 'true'
        env:
          MIKE_OPTS: "--branch gh-pages"
        run: |
          echo "Existing documentation versions:"
          mike list $MIKE_OPTS

          IFS=',' read -ra VERSION_LIST <<< "${{ steps.cleanup_version.outputs.versions }}"

          DELETED=()
          SKIPPED=()

          for VERSION in "${VERSION_LIST[@]}"; do
            if mike list $MIKE_OPTS | grep -q "^$VERSION"; then
              echo "Deleting: $VERSION"
              mike delete $MIKE_OPTS "$VERSION"
              DELETED+=("$VERSION")
            else
              echo "Not found, skipping: $VERSION"
              SKIPPED+=("$VERSION")
            fi
          done

          # Push all deletions at once
          if [[ ${#DELETED[@]} -gt 0 ]]; then
            git push origin gh-pages
          fi

          # Summary
          echo "## 🗑️ Documentation Cleanup Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "| Property | Value |" >> $GITHUB_STEP_SUMMARY
          echo "|----------|-------|" >> $GITHUB_STEP_SUMMARY
          echo "| Trigger | ${{ github.event_name }} |" >> $GITHUB_STEP_SUMMARY
          if [[ "${{ github.event_name }}" == "delete" ]]; then
            echo "| Deleted Branch | ${{ github.event.ref }} |" >> $GITHUB_STEP_SUMMARY
          fi
          echo "" >> $GITHUB_STEP_SUMMARY

          if [[ ${#DELETED[@]} -gt 0 ]]; then
            echo "### Deleted" >> $GITHUB_STEP_SUMMARY
            for v in "${DELETED[@]}"; do echo "- \`$v\`" >> $GITHUB_STEP_SUMMARY; done
            echo "" >> $GITHUB_STEP_SUMMARY
          fi

          if [[ ${#SKIPPED[@]} -gt 0 ]]; then
            echo "### Skipped (not found)" >> $GITHUB_STEP_SUMMARY
            for v in "${SKIPPED[@]}"; do echo "- \`$v\`" >> $GITHUB_STEP_SUMMARY; done
            echo "" >> $GITHUB_STEP_SUMMARY
          fi

          if [[ ${#DELETED[@]} -eq 0 ]]; then
            echo "ℹ️ No versions were deleted." >> $GITHUB_STEP_SUMMARY
          else
            echo "✅ Deleted ${#DELETED[@]} version(s) successfully!" >> $GITHUB_STEP_SUMMARY
          fi

      - name: Skip cleanup
        if: steps.cleanup_version.outputs.should_cleanup != 'true'
        run: |
          echo "## ℹ️ Documentation Cleanup Skipped" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "Reason: Protected branch, not a branch deletion, or no versions specified" >> $GITHUB_STEP_SUMMARY