1  name: docs-tests
  2  
  3  on:
  4    workflow_dispatch:
  5      inputs:
  6        debug_enabled:
  7          type: boolean
  8          description: "Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)"
  9          required: false
 10          default: false
 11    push:
 12      branches: [main, master, develop]
 13      paths:
 14        - "docs/**"
 15        - "*.md"
 16        - ".github/workflows/docs-tests.yml"
 17    pull_request:
 18      branches: [main, master, develop]
 19      paths:
 20        - "docs/**"
 21        - "*.md"
 22        - ".github/workflows/docs-tests.yml"
 23    schedule:
 24      # Run weekly to catch issues with external dependencies
 25      - cron: "0 0 * * 0"
 26  
 27  jobs:
 28    validate-documentation:
 29      name: Validate Documentation
 30      runs-on: ubuntu-latest
 31  
 32      steps:
 33        - name: Checkout repository
 34          uses: actions/checkout@v4
 35          with:
 36            submodules: recursive
 37  
 38        - name: Setup Python
 39          uses: actions/setup-python@v4
 40          with:
 41            python-version: "3.x"
 42  
 43        - name: Install system dependencies
 44          run: |
 45            sudo apt-get update
 46            sudo apt-get install -y aspell aspell-en
 47  
 48        - name: Setup tmate session
 49          uses: mxschmitt/action-tmate@v3
 50          if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
 51          env:
 52            GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 53          with:
 54            limit-access-to-actor: true
 55          timeout-minutes: 300
 56  
 57        - name: Setup Julia
 58          uses: julia-actions/setup-julia@v1
 59          with:
 60            version: "1.12"
 61  
 62        - name: Cache Julia packages
 63          uses: julia-actions/cache@v1
 64  
 65        - name: Install Python dependencies
 66          run: |
 67            python -m pip install --upgrade pip
 68            pip install -r scripts/validation/requirements.txt
 69  
 70        - name: Make scripts executable
 71          run: chmod +x scripts/validation/*.sh
 72  
 73        - name: Setup Julia environment
 74          run: |
 75            julia --project=Planar -e '
 76              using Pkg
 77              Pkg.instantiate()
 78              Pkg.precompile()
 79            '
 80        - name: Create results directory
 81          run: mkdir -p docs/test/results
 82  
 83        - name: Run documentation tests
 84          run: |
 85            julia --project=docs docs/test/runtests.jl --verbose \
 86              --output=docs/test/results/test-results.toml
 87  
 88        - name: Run Markdown complexity check
 89          run: python scripts/validation/markdown_complexity.py || true
 90  
 91        - name: Run heading hierarchy check
 92          run: python scripts/validation/heading_hierarchy.py || true
 93  
 94        - name: Run accessibility check
 95          run: bash scripts/validation/accessibility.sh || true
 96  
 97        - name: Run performance check
 98          run: bash scripts/validation/performance.sh || true
 99  
100        - name: Run spell check
101          run: bash scripts/validation/spellcheck.sh || true
102  
103        - name: Run writing issues check
104          run: bash scripts/validation/writing_issues.sh || true
105  
106        - name: Upload validation reports
107          uses: actions/upload-artifact@v4
108          if: always()
109          with:
110            name: validation-reports
111            path: |
112              docs/test/results/
113              docs/maintenance/link-check-report.md
114              docs/maintenance/template-compliance-report.md
115              docs/maintenance/freshness-report.md
116  
117        - name: Comment PR with validation results
118          uses: actions/github-script@v6
119          if: github.event_name == 'pull_request'
120          with:
121            script: |
122              const fs = require('fs');
123  
124              // Read validation reports
125              let comment = '## 📋 Documentation Validation Results\n\n';
126  
127              try {
128                // Link check results
129                if (fs.existsSync('docs/maintenance/link-check-report.md')) {
130                  const linkReport = fs.readFileSync('docs/maintenance/link-check-report.md', 'utf8');
131                  const brokenLinks = (linkReport.match(/❌/g) || []).length;
132                  if (brokenLinks === 0) {
133                    comment += '✅ **Link Validation**: All links are working\n';
134                  } else {
135                    comment += `❌ **Link Validation**: ${brokenLinks} broken links found\n`;
136                  }
137                }
138  
139                // Template compliance results
140                if (fs.existsSync('docs/maintenance/template-compliance-report.md')) {
141                  const templateReport = fs.readFileSync('docs/maintenance/template-compliance-report.md', 'utf8');
142                  const issues = (templateReport.match(/❌|⚠️/g) || []).length;
143                  if (issues === 0) {
144                    comment += '✅ **Template Compliance**: All templates followed correctly\n';
145                  } else {
146                    comment += `⚠️ **Template Compliance**: ${issues} issues found\n`;
147                  }
148                }
149  
150                comment += '\n📊 **Detailed Reports**: Check the workflow artifacts for complete validation reports.\n';
151  
152                // Add guidance for contributors
153                comment += '\n### For Contributors\n';
154                comment += 'If validation failed:\n';
155                comment += '1. Check the detailed reports in the workflow artifacts\n';
156                comment += '2. Fix any broken links or formatting issues\n';
157                comment += '3. Ensure proper frontmatter and template compliance\n';
158                comment += '4. Run validation scripts locally before pushing:\n';
159                comment += '   ```bash\n';
160                comment += '   ./scripts/check-links.sh\n';
161                comment += '   ./scripts/check-templates.sh\n';
162                comment += '   julia docs/test/runtests.jl\n';
163                comment += '   ```\n';
164                comment += '\n### Code Block Review\n';
165                comment += 'For code block consistency, please refer to the [AI Code Block Review Guide](docs/maintenance/ai-code-block-review-guide.md) for systematic review procedures.\n';
166  
167              } catch (error) {
168                comment += `❌ **Validation Error**: ${error.message}\n`;
169              }
170  
171              github.rest.issues.createComment({
172                issue_number: context.issue.number,
173                owner: context.repo.owner,
174                repo: context.repo.repo,
175                body: comment
176              });