name: Validate Documentation
on:
pull_request:
branches:
- main
paths:
- 'docs/**'
- 'mkdocs.yml'
- 'requirements.txt'
- '.github/workflows/validate-docs.yml'
workflow_dispatch:
permissions:
contents: read
pull-requests: write
jobs:
validate:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0 # Full history for git-revision-date 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 requirements.txt
- name: Validate build (strict mode)
id: build
run: |
echo "::group::Building documentation with strict mode"
mkdocs build --strict --verbose
echo "::endgroup::"
echo "build_status=✅ Success" >> $GITHUB_OUTPUT
- name: Check for warnings
id: warnings
run: |
echo "::group::Checking for build warnings"
WARNINGS=$(mkdocs build --strict 2>&1 | grep -i "warning" | wc -l)
if [ "$WARNINGS" -eq 0 ]; then
echo "warnings_status=✅ No warnings found" >> $GITHUB_OUTPUT
echo "No warnings detected"
else
echo "warnings_status=⚠️ $WARNINGS warning(s) found" >> $GITHUB_OUTPUT
echo "::warning::Found $WARNINGS warning(s) in documentation build"
mkdocs build --strict 2>&1 | grep -i "warning"
fi
echo "::endgroup::"
- name: Check for TODO/FIXME markers
id: todos
continue-on-error: true
run: |
echo "::group::Checking for TODO/FIXME markers"
TODO_COUNT=$(grep -r "TODO\|FIXME\|XXX" docs/ | wc -l || echo "0")
if [ "$TODO_COUNT" -eq 0 ]; then
echo "todos_status=✅ No TODO markers found" >> $GITHUB_OUTPUT
echo "No TODO/FIXME markers detected"
else
echo "todos_status=ℹ️ $TODO_COUNT TODO marker(s) found" >> $GITHUB_OUTPUT
echo "::notice::Found $TODO_COUNT TODO/FIXME marker(s) in documentation"
grep -rn "TODO\|FIXME\|XXX" docs/ | head -10
fi
echo "::endgroup::"
- name: Validate site size
id: size
run: |
echo "::group::Checking site size"
SITE_SIZE=$(du -sh site/ | cut -f1)
SITE_SIZE_BYTES=$(du -sb site/ | cut -f1)
echo "Total site size: $SITE_SIZE"
if [ "$SITE_SIZE_BYTES" -gt 52428800 ]; then
echo "size_status=⚠️ Site size: $SITE_SIZE (exceeds 50MB recommendation)" >> $GITHUB_OUTPUT
echo "::warning::Site size $SITE_SIZE exceeds 50MB recommendation"
else
echo "size_status=✅ Site size: $SITE_SIZE" >> $GITHUB_OUTPUT
fi
echo "::endgroup::"
- name: Check large files
id: large_files
run: |
echo "::group::Checking for large files (>200KB)"
LARGE_FILES=$(find site -type f -size +200k | wc -l)
if [ "$LARGE_FILES" -eq 0 ]; then
echo "large_files_status=✅ No large files found" >> $GITHUB_OUTPUT
else
echo "large_files_status=⚠️ $LARGE_FILES file(s) larger than 200KB" >> $GITHUB_OUTPUT
echo "::warning::Found $LARGE_FILES file(s) larger than 200KB"
echo "Largest files:"
find site -type f -exec du -h {} + | sort -rh | head -10
fi
echo "::endgroup::"
- name: Validate navigation structure
id: navigation
run: |
echo "::group::Validating navigation structure"
# Check if all files in mkdocs.yml exist
python3 << 'EOF'
import yaml
import os
import sys
with open('mkdocs.yml', 'r') as f:
config = yaml.safe_load(f)
missing_files = []
def check_nav_items(items, prefix=''):
for item in items:
if isinstance(item, dict):
for key, value in item.items():
if isinstance(value, str):
# It's a file reference
file_path = os.path.join('docs', value)
if not os.path.exists(file_path):
missing_files.append(value)
elif isinstance(value, list):
# It's a nested structure
check_nav_items(value, prefix + key + ' > ')
if 'nav' in config:
check_nav_items(config['nav'])
if missing_files:
print(f"::error::Missing files referenced in navigation: {', '.join(missing_files)}")
sys.exit(1)
else:
print("✅ All navigation files exist")
EOF
echo "navigation_status=✅ Navigation structure valid" >> $GITHUB_OUTPUT
echo "::endgroup::"
- name: Generate validation summary
if: always()
run: |
echo "## Documentation Validation Summary :clipboard:" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "### Build Validation" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "| Check | Status |" >> $GITHUB_STEP_SUMMARY
echo "|-------|--------|" >> $GITHUB_STEP_SUMMARY
echo "| Build (strict mode) | ${{ steps.build.outputs.build_status || '❌ Failed' }} |" >> $GITHUB_STEP_SUMMARY
echo "| Warnings | ${{ steps.warnings.outputs.warnings_status || 'N/A' }} |" >> $GITHUB_STEP_SUMMARY
echo "| TODO markers | ${{ steps.todos.outputs.todos_status || 'N/A' }} |" >> $GITHUB_STEP_SUMMARY
echo "| Site size | ${{ steps.size.outputs.size_status || 'N/A' }} |" >> $GITHUB_STEP_SUMMARY
echo "| Large files | ${{ steps.large_files.outputs.large_files_status || 'N/A' }} |" >> $GITHUB_STEP_SUMMARY
echo "| Navigation | ${{ steps.navigation.outputs.navigation_status || 'N/A' }} |" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "### Next Steps" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "- Review validation results above" >> $GITHUB_STEP_SUMMARY
echo "- Fix any errors or warnings before merging" >> $GITHUB_STEP_SUMMARY
echo "- Consider optimizing large files if found" >> $GITHUB_STEP_SUMMARY
echo "- Ensure all TODO markers are addressed or documented" >> $GITHUB_STEP_SUMMARY
- name: Comment PR
if: github.event_name == 'pull_request'
uses: actions/github-script@v7
with:
script: |
const buildStatus = '${{ steps.build.outputs.build_status || '❌ Failed' }}';
const warningsStatus = '${{ steps.warnings.outputs.warnings_status || 'N/A' }}';
const todosStatus = '${{ steps.todos.outputs.todos_status || 'N/A' }}';
const sizeStatus = '${{ steps.size.outputs.size_status || 'N/A' }}';
const largeFilesStatus = '${{ steps.large_files.outputs.large_files_status || 'N/A' }}';
const navigationStatus = '${{ steps.navigation.outputs.navigation_status || 'N/A' }}';
const comment = `## Documentation Validation Results :clipboard:
### Build Validation
| Check | Status |
|-------|--------|
| Build (strict mode) | ${buildStatus} |
| Warnings | ${warningsStatus} |
| TODO markers | ${todosStatus} |
| Site size | ${sizeStatus} |
| Large files | ${largeFilesStatus} |
| Navigation | ${navigationStatus} |
### Recommendations
${buildStatus.includes('❌') ? '- ⚠️ **Fix build errors before merging**\n' : ''}
${warningsStatus.includes('⚠️') ? '- 💡 Consider addressing build warnings\n' : ''}
${sizeStatus.includes('⚠️') ? '- 💡 Consider optimizing site size (currently exceeds 50MB)\n' : ''}
${largeFilesStatus.includes('⚠️') ? '- 💡 Consider optimizing large files (>200KB)\n' : ''}
${todosStatus.includes('ℹ️') ? '- ℹ️ TODO markers found - ensure they are documented\n' : ''}
---
*This validation runs automatically on documentation changes*`;
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: comment
});
