Documentation Automation #355
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Documentation Automation | |
| on: | |
| push: | |
| paths: | |
| - 'docs/**' | |
| - '*.md' | |
| - '.github/workflows/documentation-automation.yml' | |
| schedule: | |
| # Run every 6 hours | |
| - cron: '0 */6 * * *' | |
| workflow_dispatch: | |
| inputs: | |
| task: | |
| description: 'Specific task to run' | |
| required: false | |
| default: 'all' | |
| type: choice | |
| options: | |
| - all | |
| - update-docs | |
| - validate-docs | |
| - mcp-analysis | |
| - generate-reports | |
| env: | |
| PYTHON_VERSION: '3.9' | |
| MCP_USAGE_TARGETS: | | |
| context7: 15-20 | |
| brave_search: 10-15 | |
| github_mcp: maintain_high | |
| playwright: 8-12 | |
| jobs: | |
| automation-preflight: | |
| name: Documentation Assets Check | |
| runs-on: ubuntu-latest | |
| outputs: | |
| enabled: ${{ steps.detect.outputs.enabled }} | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| - name: Detect documentation automation assets | |
| id: detect | |
| run: | | |
| if [ -f docs/automation/scripts/requirements.txt ]; then | |
| echo "enabled=true" >> "$GITHUB_OUTPUT" | |
| echo "Automation assets detected; downstream jobs will execute." | |
| else | |
| echo "enabled=false" >> "$GITHUB_OUTPUT" | |
| echo "Automation assets not found; documentation automation jobs will be skipped." | |
| fi | |
| update-documentation: | |
| name: Update Living Documentation | |
| runs-on: ubuntu-latest | |
| needs: automation-preflight | |
| if: needs.automation-preflight.outputs.enabled == 'true' | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| token: ${{ secrets.GITHUB_TOKEN }} | |
| - name: Set up Python | |
| uses: actions/setup-python@v4 | |
| with: | |
| python-version: ${{ env.PYTHON_VERSION }} | |
| - name: Cache Python dependencies | |
| uses: actions/cache@v3 | |
| with: | |
| path: ~/.cache/pip | |
| key: ${{ runner.os }}-pip-${{ hashFiles('docs/automation/scripts/requirements.txt') }} | |
| restore-keys: | | |
| ${{ runner.os }}-pip- | |
| - name: Install dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install -r docs/automation/scripts/requirements.txt | |
| - name: Update current status | |
| run: | | |
| python docs/automation/scripts/change_log_generator.py --update-status | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| - name: Update change log | |
| run: | | |
| python docs/automation/scripts/change_log_generator.py --auto-update | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| - name: Update research findings | |
| run: | | |
| python docs/automation/scripts/research_synthesizer.py --update-findings | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| - name: Commit documentation updates | |
| run: | | |
| git config --local user.email "action@github.com" | |
| git config --local user.name "GitHub Action" | |
| git add docs/project-state/ | |
| git diff --staged --quiet || git commit -m "Automated documentation update [$(date -u +%Y-%m-%d\ %H:%M:%S)]" | |
| git push || echo "No changes to push" | |
| validate-documentation: | |
| name: Validate Documentation Quality | |
| runs-on: ubuntu-latest | |
| needs: [automation-preflight, update-documentation] | |
| if: needs.automation-preflight.outputs.enabled == 'true' | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| - name: Set up Python | |
| uses: actions/setup-python@v4 | |
| with: | |
| python-version: ${{ env.PYTHON_VERSION }} | |
| - name: Cache Python dependencies | |
| uses: actions/cache@v3 | |
| with: | |
| path: ~/.cache/pip | |
| key: ${{ runner.os }}-pip-${{ hashFiles('docs/automation/scripts/requirements.txt') }} | |
| restore-keys: | | |
| ${{ runner.os }}-pip- | |
| - name: Install dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install -r docs/automation/scripts/requirements.txt | |
| - name: Validate documentation structure | |
| run: | | |
| python docs/automation/scripts/documentation_validator.py --check-structure | |
| continue-on-error: true | |
| - name: Validate template compliance | |
| run: | | |
| python docs/automation/scripts/documentation_validator.py --check-templates | |
| continue-on-error: true | |
| - name: Validate MCP integration | |
| run: | | |
| python docs/automation/scripts/documentation_validator.py --check-mcp-integration | |
| continue-on-error: true | |
| - name: Generate validation report | |
| run: | | |
| python docs/automation/scripts/documentation_validator.py --generate-report | |
| continue-on-error: true | |
| - name: Upload validation report | |
| uses: actions/upload-artifact@v3 | |
| if: always() | |
| with: | |
| name: documentation-validation-report | |
| path: docs/automation/reports/validation-report.md | |
| mcp-usage-analysis: | |
| name: MCP Usage Analysis and Optimization | |
| runs-on: ubuntu-latest | |
| needs: [automation-preflight, validate-documentation] | |
| if: needs.automation-preflight.outputs.enabled == 'true' | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| token: ${{ secrets.GITHUB_TOKEN }} | |
| - name: Set up Python | |
| uses: actions/setup-python@v4 | |
| with: | |
| python-version: ${{ env.PYTHON_VERSION }} | |
| - name: Cache Python dependencies | |
| uses: actions/cache@v3 | |
| with: | |
| path: ~/.cache/pip | |
| key: ${{ runner.os }}-pip-${{ hashFiles('docs/automation/scripts/requirements.txt') }} | |
| restore-keys: | | |
| ${{ runner.os }}-pip- | |
| - name: Install dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install -r docs/automation/scripts/requirements.txt | |
| - name: Analyze MCP usage | |
| run: | | |
| python docs/automation/scripts/mcp_usage_tracker.py --weekly-report > docs/automation/reports/mcp-weekly-report.md | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| - name: Generate optimization analysis | |
| run: | | |
| python docs/automation/scripts/mcp_usage_tracker.py --optimization-analysis > docs/automation/reports/mcp-optimization-analysis.json | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| - name: Update MCP optimization guide | |
| run: | | |
| python docs/automation/scripts/mcp_usage_tracker.py --update-guide | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| - name: Commit MCP analysis updates | |
| run: | | |
| git config --local user.email "action@github.com" | |
| git config --local user.name "GitHub Action" | |
| git add docs/mcp-integration/mcp-optimization.md | |
| git add docs/automation/reports/ | |
| git diff --staged --quiet || git commit -m "Automated MCP usage analysis [$(date -u +%Y-%m-%d\ %H:%M:%S)]" | |
| git push || echo "No changes to push" | |
| generate-reports: | |
| name: Generate Comprehensive Reports | |
| runs-on: ubuntu-latest | |
| needs: [automation-preflight, update-documentation, validate-documentation, mcp-usage-analysis] | |
| if: needs.automation-preflight.outputs.enabled == 'true' && always() | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| - name: Set up Python | |
| uses: actions/setup-python@v4 | |
| with: | |
| python-version: ${{ env.PYTHON_VERSION }} | |
| - name: Cache Python dependencies | |
| uses: actions/cache@v3 | |
| with: | |
| path: ~/.cache/pip | |
| key: ${{ runner.os }}-pip-${{ hashFiles('docs/automation/scripts/requirements.txt') }} | |
| restore-keys: | | |
| ${{ runner.os }}-pip- | |
| - name: Install dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install -r docs/automation/scripts/requirements.txt | |
| - name: Generate comprehensive report | |
| run: | | |
| python docs/automation/scripts/research_synthesizer.py --comprehensive-report > docs/automation/reports/comprehensive-report.md | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| - name: Generate visualizations | |
| run: | | |
| python docs/automation/scripts/mcp_usage_tracker.py --generate-charts | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| - name: Upload comprehensive report | |
| uses: actions/upload-artifact@v3 | |
| with: | |
| name: comprehensive-documentation-report | |
| path: | | |
| docs/automation/reports/ | |
| docs/automation/charts/ | |
| notify-results: | |
| name: Notify Results | |
| runs-on: ubuntu-latest | |
| needs: [automation-preflight, update-documentation, validate-documentation, mcp-usage-analysis, generate-reports] | |
| if: always() | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| - name: Log automation skip notice | |
| if: needs.automation-preflight.outputs.enabled != 'true' | |
| run: echo "Documentation automation assets missing; skipping notification checks." | |
| - name: Check for alerts | |
| if: needs.automation-preflight.outputs.enabled == 'true' | |
| run: | | |
| # Check MCP usage targets | |
| python -c " | |
| import json | |
| import sys | |
| try: | |
| with open('docs/automation/reports/mcp-optimization-analysis.json', 'r') as f: | |
| analysis = json.load(f) | |
| alerts = [] | |
| for rec in analysis.get('recommendations', []): | |
| if rec['issue'] in ['low_usage', 'low_quality', 'low_success_rate']: | |
| alerts.append(f'{rec[\"server\"]}: {rec[\"recommendation\"]}') | |
| if alerts: | |
| print('::warning:: MCP Usage Alerts:') | |
| for alert in alerts: | |
| print(f'::warning:: {alert}') | |
| except: | |
| pass | |
| " | |
| - name: Create issue for critical alerts | |
| if: needs.automation-preflight.outputs.enabled == 'true' && failure() | |
| uses: actions/github-script@v6 | |
| with: | |
| script: | | |
| const title = `Documentation Automation Alert - ${new Date().toISOString()}`; | |
| const body = `## Documentation Automation Failed | |
| The documentation automation workflow has detected issues that require attention. | |
| Please check the workflow logs for details and take appropriate action. | |
| **Workflow Run**: ${context.payload.repository.html_url}/actions/runs/${context.runId} | |
| **Time**: ${new Date().toISOString()} | |
| `; | |
| github.rest.issues.create({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| title: title, | |
| body: body, | |
| labels: ['documentation', 'automation', 'alert'] | |
| }); |