name: Documentation

# Build and deploy documentation to GitHub Pages
on:
  # Trigger on releases
  release:
    types: [published]

  # Trigger on pushes to main (for docs updates)
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'claude_force/**/*.py'
      - '.github/workflows/docs.yml'

  # Allow manual trigger
  workflow_dispatch:

# Sets permissions for GitHub Pages deployment
permissions:
  contents: read
  pages: write
  id-token: write

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

jobs:
  # Build documentation
  build:
    name: Build Documentation
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for versioning

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: 'pip'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[dev]"
          pip install -r docs/requirements.txt

      - name: Extract version
        id: version
        run: |
          if [ "${{ github.event_name }}" = "release" ]; then
            VERSION=${GITHUB_REF#refs/tags/v}
          else
            VERSION=$(python -c "import claude_force; print(claude_force.__version__)")
          fi
          echo "version=${VERSION}" >> $GITHUB_OUTPUT
          echo "Building docs for version: $VERSION"

      - name: Update conf.py version
        run: |
          VERSION="${{ steps.version.outputs.version }}"
          sed -i "s/^release = .*/release = \"$VERSION\"/" docs/conf.py
          sed -i "s/^version = .*/version = \"$VERSION\"/" docs/conf.py

      - name: Build Sphinx documentation
        run: |
          cd docs
          sphinx-build -b html . _build/html -W --keep-going

      - name: Create versions file
        run: |
          # Create a versions.json for version selector (future enhancement)
          cat > docs/_build/html/versions.json <<EOF
          {
            "current": "${{ steps.version.outputs.version }}",
            "versions": [
              {"name": "${{ steps.version.outputs.version }}", "url": "/"}
            ]
          }
          EOF

      - name: Add .nojekyll file
        run: |
          # Prevent Jekyll processing on GitHub Pages
          touch docs/_build/html/.nojekyll

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/_build/html

  # Deploy to GitHub Pages
  deploy:
    name: Deploy to GitHub Pages
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

  # Notify on deployment
  notify:
    name: Notify Deployment
    needs: deploy
    runs-on: ubuntu-latest
    if: success()
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Extract version
        id: version
        run: |
          if [ "${{ github.event_name }}" = "release" ]; then
            VERSION=${GITHUB_REF#refs/tags/v}
          else
            VERSION=$(python -c "import sys; sys.path.insert(0, '.'); import claude_force; print(claude_force.__version__)" || echo "dev")
          fi
          echo "version=${VERSION}" >> $GITHUB_OUTPUT

      - name: Display deployment info
        run: |
          echo "✅ Documentation deployed successfully!"
          echo "📚 Documentation URL: ${{ needs.deploy.outputs.page_url }}"
          echo "📦 Version: ${{ steps.version.outputs.version }}"
          echo ""
          echo "The documentation is now live and accessible."
