pr-docs.yml

name: PR Documentation Check

on:
  pull_request:
    branches: [ main ]
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  docs-check:
    runs-on: ubuntu-latest
    name: Documentation Check
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Detect documentation changes
        uses: dorny/paths-filter@v2
        id: changes
        with:
          filters: |
            code:
              - 'neural/**/*.py'
            docs:
              - 'docs/**'
              - 'docs-site/**'
            examples:
              - 'examples/**'
            readme:
              - 'README.md'

      - name: Set up uv
        if: steps.changes.outputs.code == 'true' || steps.changes.outputs.examples == 'true'
        uses: astral-sh/setup-uv@v7
        with:
          python-version: "3.11"
          enable-cache: true

      - name: Sync dependencies
        if: steps.changes.outputs.code == 'true' || steps.changes.outputs.examples == 'true'
        run: uv sync --extra dev

      - name: Check for docstring coverage
        if: steps.changes.outputs.code == 'true'
        run: |
          uv run python scripts/check_docstring_coverage.py

      - name: Validate example documentation
        if: steps.changes.outputs.examples == 'true'
        run: |
          uv run python scripts/validate_examples.py

      - name: Check for API documentation updates
        if: steps.changes.outputs.code == 'true'
        run: |
          uv run python scripts/validate_docs.py

      - name: Comment on PR
        if: always()
        continue-on-error: true
        uses: actions/github-script@v6
        with:
          script: |
            const { data: comments } = await github.rest.issues.listComments({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
            });
            
            const botComment = comments.find(comment => 
              comment.user.type === 'Bot' && 
              comment.body.includes('📚 Documentation Status')
            );
            
            let commentBody = '## 📚 Documentation Status\n\n';
            
            if ('${{ steps.changes.outputs.code }}' === 'true') {
              commentBody += '✅ Code changes detected\n';
              commentBody += '- Docstring coverage checked\n';
              commentBody += '- API documentation validation completed\n';
            }
            
            if ('${{ steps.changes.outputs.docs }}' === 'true') {
              commentBody += '✅ Documentation changes detected\n';
              commentBody += '- Documentation structure validated\n';
              commentBody += '- Links checked for broken references\n';
            }
            
            if ('${{ steps.changes.outputs.examples }}' === 'true') {
              commentBody += '✅ Example changes detected\n';
              commentBody += '- Example documentation validated\n';
              commentBody += '- Code syntax verified\n';
            }
            
            if ('${{ steps.changes.outputs.readme }}' === 'true') {
              commentBody += '✅ README changes detected\n';
            }
            
            if ('${{ steps.changes.outputs.code }}' === 'false' && 
                '${{ steps.changes.outputs.docs }}' === 'false' && 
                '${{ steps.changes.outputs.examples }}' === 'false' && 
                '${{ steps.changes.outputs.readme }}' === 'false') {
              commentBody += 'ℹ️ No documentation-related changes detected\n';
            }
            
            commentBody += '\n---\n*This comment is automatically generated by the documentation workflow.*';
            
            if (botComment) {
              await github.rest.issues.updateComment({
                comment_id: botComment.id,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: commentBody,
              });
            } else {
              await github.rest.issues.createComment({
                issue_number: context.issue.number,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: commentBody,
              });
            }

  require-docs:
    runs-on: ubuntu-latest
    name: Require Documentation
    if: github.event.pull_request.draft == false
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Check if documentation is required
        uses: actions/github-script@v6
        with:
          script: |
            const { execSync } = require('child_process');
            
            // Get changed files
            const diff = execSync('git diff --name-only origin/main...HEAD', { encoding: 'utf8' });
            const changedFiles = diff.trim().split('\n');
            
            // Check if code changes require documentation
            const codeFiles = changedFiles.filter(file => file.startsWith('neural/') && file.endsWith('.py'));
            const docFiles = changedFiles.filter(file =>
              file.startsWith('docs/') ||
              file.startsWith('docs-site/') ||
              file === 'README.md'
            );
            
            console.log('Code files changed:', codeFiles.length);
            console.log('Doc files changed:', docFiles.length);
            
            if (codeFiles.length > 0 && docFiles.length === 0) {
              // Check if changes are minor (don't require docs)
              const minorChanges = execSync(`git log --format=%s origin/main...HEAD | grep -E "^(fix|chore|refactor|style|test)" | wc -l`, { encoding: 'utf8' });
              
              if (parseInt(minorChanges.trim()) < codeFiles.length) {
                console.log('⚠️ Documentation may be required for these changes');
                console.log('Consider updating:');
                console.log('- API documentation for new functions/classes');
                console.log('- Examples for new features');
                console.log('- README for breaking changes');
                
                // This doesn't fail the build, just provides guidance
                process.exit(0);
              }
            }
            
            console.log('✅ Documentation requirements satisfied');