docs.yml

name: Documentation

on:
  push:
    branches: [ main ]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - 'requirements.txt'
      - 'pkg/**'
      - '.github/workflows/docs.yml'
  pull_request:
    branches: [ main ]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - 'requirements.txt'
      - 'pkg/**'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  GO_VERSION: '1.25'

jobs:
  build:
    name: Build Documentation
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v5
      with:
        fetch-depth: 0

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

    - name: Set up Go
      uses: actions/setup-go@v6
      with:
        go-version: ${{ env.GO_VERSION }}
        cache: false

    - name: Cache Python dependencies
      uses: actions/cache@v5
      with:
        path: ~/.cache/pip
        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
        restore-keys: |
          ${{ runner.os }}-pip-

    - name: Cache Go modules
      uses: actions/cache@v5
      with:
        path: |
          ~/.cache/go-build
          ~/go/pkg/mod
        key: ${{ runner.os }}-go-v2-${{ hashFiles('**/go.sum') }}
        restore-keys: |
          ${{ runner.os }}-go-v2-

    - name: Install Python dependencies
      run: |
        python -m pip install --upgrade pip
        if [ -f requirements.txt ]; then
          pip install -r requirements.txt
        else
          pip install mkdocs mkdocs-material mkdocs-mermaid2-plugin
        fi

    - name: Install Go dependencies
      run: |
        go mod download
        go mod tidy

    - name: Generate Go documentation
      run: |
        mkdir -p docs/api
        echo "# Go Package Documentation" > docs/api/generated.md
        echo "" >> docs/api/generated.md
        echo "Auto-generated API documentation for all packages." >> docs/api/generated.md
        echo "" >> docs/api/generated.md

        for pkg in $(go list ./pkg/...); do
          echo "## Package: $pkg" >> docs/api/generated.md
          echo "" >> docs/api/generated.md
          echo '```go' >> docs/api/generated.md
          go doc -all $pkg >> docs/api/generated.md 2>/dev/null || echo "No documentation available"
          echo '```' >> docs/api/generated.md
          echo "" >> docs/api/generated.md
        done

    - name: Build documentation
      run: |
        if [ -f mkdocs.yml ]; then
          mkdocs build --verbose
        else
          echo "No mkdocs.yml found, creating minimal documentation structure"
          mkdir -p site
          echo "<html><head><title>GoLangGraph Docs</title></head><body><h1>GoLangGraph Documentation</h1><p>Documentation site is under construction.</p></body></html>" > site/index.html
        fi

    - name: Test documentation links
      run: |
        # Install link checker
        pip install pytest-html-reporter

        # Basic validation - check if HTML files were generated
        if [ ! -d "site" ]; then
          echo "Error: Documentation site not built"
          exit 1
        fi

        # Count HTML files
        HTML_COUNT=$(find site -name "*.html" | wc -l)
        echo "Generated $HTML_COUNT HTML files"

        if [ $HTML_COUNT -eq 0 ]; then
          echo "Error: No HTML files generated"
          exit 1
        fi

        # Check for common issues
        find site -name "*.html" -exec grep -l "404\|Not Found\|Error" {} \; | head -5 | while read file; do
          echo "Warning: Potential issue in $file"
        done

    - name: Upload documentation artifacts
      uses: actions/upload-artifact@v6
      with:
        name: documentation
        path: site/
        retention-days: 7

    - name: Upload documentation coverage
      uses: actions/upload-artifact@v6
      with:
        name: documentation-coverage
        path: docs/api/generated.md
        retention-days: 7

  deploy:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest
    needs: build
    # Pages is optional for this repository. Keep documentation builds required,
    # but only deploy after an administrator explicitly enables it as a variable.
    if: github.ref == 'refs/heads/main' && github.event_name == 'push' && vars.DEPLOY_GITHUB_PAGES == 'true'

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

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
    - name: Download documentation artifacts
      uses: actions/download-artifact@v6
      with:
        name: documentation
        path: site/

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

    - name: Upload to GitHub Pages
      uses: actions/upload-pages-artifact@v3
      with:
        path: site/

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

    - name: Summary
      run: |
        echo "## Documentation Deployed 🚀" >> $GITHUB_STEP_SUMMARY
        echo "" >> $GITHUB_STEP_SUMMARY
        echo "📚 **Documentation URL:** ${{ steps.deployment.outputs.page_url }}" >> $GITHUB_STEP_SUMMARY
        echo "🔗 **Direct Link:** [View Documentation](${{ steps.deployment.outputs.page_url }})" >> $GITHUB_STEP_SUMMARY
        echo "" >> $GITHUB_STEP_SUMMARY
        echo "### What's Included:" >> $GITHUB_STEP_SUMMARY
        echo "- Getting Started Guide" >> $GITHUB_STEP_SUMMARY
        echo "- API Reference" >> $GITHUB_STEP_SUMMARY
        echo "- Examples and Tutorials" >> $GITHUB_STEP_SUMMARY
        echo "- Architecture Documentation" >> $GITHUB_STEP_SUMMARY