deploy-site.yml

# Workflow for deploying versioned documentation to GitHub Pages
name: Deploy Documentation

on:
  # Runs on pushes targeting the default branch (publishes to /snapshot/)
  push:
    branches: ["main"]
    paths:
      - 'pom.xml'
      - 'src/**'
      - '.github/**'

  # Runs on release publish (publishes to /latest/ and /vX.Y.Z/)
  release:
    types: [published]

  # Allows manual trigger
  workflow_dispatch:
    inputs:
      version:
        description: 'Specific version/tag to build (leave empty for snapshot from main)'
        type: string
        default: ''
      publish_as_latest:
        description: 'Also publish as latest?'
        type: boolean
        default: false
      rebuild_all_versions:
        description: 'Rebuild documentation for all release tags?'
        type: boolean
        default: false

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: write
  pages: write
  id-token: write

# Allow only one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Set up JDK 17
        uses: actions/setup-java@v5
        with:
          java-version: '17'
          distribution: 'temurin'

      - name: Checkout gh-pages branch
        uses: actions/checkout@v6
        with:
          ref: gh-pages
          path: site
        continue-on-error: true

      - name: Initialize site if needed
        run: |
          if [ ! -d "site/.git" ]; then
            rm -rf site
            mkdir -p site
            cd site
            git init
            git checkout -b gh-pages
            git remote add origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git"
          fi

      - name: Get all release tags
        id: tags
        run: |
          # Get all tags that look like version numbers (v1.0.0 or 1.0.0)
          TAGS=$(git tag -l | grep -E '^v?[0-9]+\.[0-9]+' | sort -Vr)
          echo "all_tags<<EOF" >> $GITHUB_OUTPUT
          echo "$TAGS" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT
          
          # Get the latest tag
          LATEST_TAG=$(echo "$TAGS" | head -n 1)
          echo "latest_tag=$LATEST_TAG" >> $GITHUB_OUTPUT
          
          # Determine what to build
          if [[ "${{ github.event_name }}" == "release" ]]; then
            echo "build_tag=${{ github.event.release.tag_name }}" >> $GITHUB_OUTPUT
            echo "is_release=true" >> $GITHUB_OUTPUT
          elif [[ -n "${{ inputs.version }}" ]]; then
            # Manual trigger with specific version
            VERSION="${{ inputs.version }}"
            # Add 'v' prefix if not present for tag lookup
            if [[ ! "$VERSION" =~ ^v ]]; then
              TAG="v$VERSION"
            else
              TAG="$VERSION"
            fi
            echo "build_tag=$TAG" >> $GITHUB_OUTPUT
            echo "is_release=true" >> $GITHUB_OUTPUT
          else
            echo "build_tag=" >> $GITHUB_OUTPUT
            echo "is_release=false" >> $GITHUB_OUTPUT
          fi

      - name: Build snapshot documentation (main branch)
        if: steps.tags.outputs.is_release == 'false' && inputs.rebuild_all_versions != true
        run: |
          ./mvnw clean site -DskipTests -Dcheckstyle.skip=true
          
          rm -rf "site/snapshot"
          mkdir -p "site/snapshot"
          cp -r target/site/* "site/snapshot/"

      - name: Build documentation for specific version
        if: steps.tags.outputs.is_release == 'true' && inputs.rebuild_all_versions != true
        run: |
          TAG="${{ steps.tags.outputs.build_tag }}"
          VERSION="${TAG#v}"  # Remove 'v' prefix
          
          echo "Building documentation for $TAG (version $VERSION)"
          git checkout "$TAG"
          
          ./mvnw clean site -DskipTests -Dcheckstyle.skip=true
          
          rm -rf "site/$VERSION"
          mkdir -p "site/$VERSION"
          cp -r target/site/* "site/$VERSION/"
          
          # Update /latest/ if this is a release event or publish_as_latest is true
          if [[ "${{ github.event_name }}" == "release" ]] || [[ "${{ inputs.publish_as_latest }}" == "true" ]]; then
            rm -rf "site/latest"
            mkdir -p "site/latest"
            cp -r target/site/* "site/latest/"
          fi
          
          git checkout main

      - name: Build documentation for all release tags
        if: inputs.rebuild_all_versions == true
        run: |
          LATEST_TAG="${{ steps.tags.outputs.latest_tag }}"
          
          while IFS= read -r TAG; do
            if [[ -z "$TAG" ]]; then continue; fi
            
            VERSION="${TAG#v}"  # Remove 'v' prefix
            echo "Building documentation for $TAG (version $VERSION)"
            
            git checkout "$TAG"
            ./mvnw clean site -DskipTests -Dcheckstyle.skip=true
            
            rm -rf "site/$VERSION"
            mkdir -p "site/$VERSION"
            cp -r target/site/* "site/$VERSION/"
            
            # If this is the latest tag, also update /latest/
            if [[ "$TAG" == "$LATEST_TAG" ]]; then
              rm -rf "site/latest"
              mkdir -p "site/latest"
              cp -r target/site/* "site/latest/"
            fi
            
          done <<< "${{ steps.tags.outputs.all_tags }}"
          
          # Return to main and build snapshot
          git checkout main
          ./mvnw clean site -DskipTests -Dcheckstyle.skip=true
          
          rm -rf "site/snapshot"
          mkdir -p "site/snapshot"
          cp -r target/site/* "site/snapshot/"

      - name: Copy version index page
        run: |
          cp .github/templates/versions.html site/index.html

      - name: Update version list from git tags
        run: |
          cd site
          
          # Get versions from git tags (already sorted by version, descending)
          VERSIONS=$(git -C .. tag -l | grep -E '^v?[0-9]+\.[0-9]+' | sed 's/^v//' | sort -Vr)
          HAS_SNAPSHOT=$([ -d "snapshot" ] && echo "true" || echo "false")
          
          # Generate version links
          VERSION_HTML=""
          IS_FIRST_VERSION="true"
          
          # Add snapshot if exists
          if [ "$HAS_SNAPSHOT" = "true" ]; then
            VERSION_HTML+='<li><a href="./snapshot/">Development (main branch)</a><span class="badge snapshot">snapshot</span></li>'
          fi
          
          # Add versioned releases from tags (first one is latest)
          for v in $VERSIONS; do
            if [ -d "$v" ]; then
              if [ "$IS_FIRST_VERSION" = "true" ]; then
                VERSION_HTML+="<li class=\"latest-version\"><a href=\"./$v/\">Version $v</a><span class=\"badge latest\">latest</span></li>"
                IS_FIRST_VERSION="false"
              else
                VERSION_HTML+="<li><a href=\"./$v/\">Version $v</a><span class=\"badge archived\">$v</span></li>"
              fi
            fi
          done
          
          # Update the index.html using the placeholder
          sed -i "s|<!-- VERSION_LIST_PLACEHOLDER -->|$VERSION_HTML|" index.html

      - name: Deploy to GitHub Pages
        run: |
          cd site
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          
          # Set remote URL with token for authentication
          git remote set-url origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" 2>/dev/null || \
            git remote add origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git"
          
          git add -A
          
          # Create descriptive commit message
          if [[ "${{ inputs.rebuild_all_versions }}" == "true" ]]; then
            COMMIT_MSG="Rebuild documentation for all versions"
          elif [[ "${{ steps.tags.outputs.is_release }}" == "true" ]]; then
            COMMIT_MSG="Deploy documentation: ${{ steps.tags.outputs.build_tag }}"
          else
            COMMIT_MSG="Deploy documentation: snapshot"
          fi
          
          git diff --staged --quiet || git commit -m "$COMMIT_MSG"
          
          # Push, creating the branch if it doesn't exist
          git push -u origin gh-pages --force
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: 'site'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4