deploy-docs.yml

name: Deploy Documentation

on:
  push:
    branches: [ main, master, develop ]
    paths:
      - 'docs/**'
      - '.github/workflows/deploy-docs.yml'
  pull_request:
    branches: [ main, master ]
    paths:
      - 'docs/**'

  # Allow manual triggering
  workflow_dispatch:

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

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

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Fetch full history for git-revision-date-localized plugin

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
          cache: 'pip'

      - name: Install dependencies
        run: |
          pip install --upgrade pip
          pip install -r docs/requirements.txt

      - name: Configure Git for git-revision-date-localized
        run: |
          git config --global user.name "GitHub Actions"
          git config --global user.email "actions@github.com"

      - name: Build documentation
        run: |
          echo "🚀 Building MkDocs documentation (NOT Maven project)"
          echo "Working directory: $(pwd)"
          echo "Repository contents:"
          ls -la

          echo "📁 Navigating to documentation directory..."
          cd docs/src/site/documentation
          echo "MkDocs directory: $(pwd)"
          echo "Documentation files:"
          ls -la

          echo "📄 Checking MkDocs configuration..."
          if [ ! -f "mkdocs.yml" ]; then
            echo "❌ ERROR: mkdocs.yml not found!"
            exit 1
          fi

          echo "🔧 Validating MkDocs installation..."
          mkdocs --version

          echo "🏗️ Building documentation with MkDocs..."
          mkdocs build --verbose

          echo "✅ MkDocs build completed successfully!"
          echo "📊 Build output:"
          ls -la site/

      - name: Upload documentation artifacts
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/src/site/documentation/site

  # Deploy job - on main/master pushes OR manual workflow dispatch
  deploy:
    if: (github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')) || github.event_name == 'workflow_dispatch'
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

  # Validation job for PRs
  validate:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Documentation build validation
        run: |
          echo "✅ Documentation builds successfully"
          echo "📝 Review the documentation changes in this PR"
          echo "🚀 Documentation will be deployed when PR is merged"