Skip to content

Documentation Automation

Purpose

Scripts and strategies for automating documentation generation, validation, and maintenance in AudioLab.

Contents

Scripts

  • generate_docs.ps1 - Master script to generate all documentation
  • validate_docs.ps1 - Check documentation quality (links, spelling, formatting)

Guides

  • changelog_automation.md - Auto-generate changelogs from commits
  • api_diff_generation.md - Detect and document API changes between versions

Quick Start

Generate All Documentation

.\generate_docs.ps1 -Target all -Clean

Generate Specific Documentation

# API docs only (Doxygen)
.\generate_docs.ps1 -Target api

# User docs only (MkDocs)
.\generate_docs.ps1 -Target user

# Diagrams only (PlantUML)
.\generate_docs.ps1 -Target diagrams

Validate Documentation

# Run all validation checks
.\validate_docs.ps1 -All

# Check specific aspects
.\validate_docs.ps1 -CheckLinks -CheckSpelling

Serve Documentation Locally

# MkDocs development server with live reload
.\generate_docs.ps1 -Target user -Serve

Master Generation Script

generate_docs.ps1

Features: - Generates API docs (Doxygen) - Generates user docs (MkDocs) - Generates diagrams (PlantUML) - Clean builds - Development server - Error reporting - Timing information

Usage: 

# Full build
.\generate_docs.ps1 -Target all -Clean

# Incremental build
.\generate_docs.ps1 -Target user

# Development mode
.\generate_docs.ps1 -Target user -Serve

Requirements: - Doxygen (for API docs) - Python + MkDocs (for user docs) - PlantUML + Java (for diagrams)

validate_docs.ps1

Features: - Check broken links (internal/external) - Spell checking (cSpell) - Markdown formatting (markdownlint) - Empty file detection - TODO/FIXME detection

Usage: 

# All checks
.\validate_docs.ps1 -All

# Specific checks
.\validate_docs.ps1 -CheckLinks
.\validate_docs.ps1 -CheckSpelling
.\validate_docs.ps1 -CheckFormat

Requirements: - markdown-link-check (npm) - cspell (npm) - markdownlint-cli (npm)

Automation Workflows

Pre-Commit Hook

# .git/hooks/pre-commit
#!/bin/bash

# Validate docs before commit
powershell.exe -File "2 - FOUNDATION/03_INFRA/03_11_documentation_platform/03_11_05_documentation_automation/validate_docs.ps1" -CheckLinks -CheckFormat

if [ $? -ne 0 ]; then
    echo "Documentation validation failed. Fix errors before committing."
    exit 1
fi

CI/CD Pipeline

# .github/workflows/docs.yml
name: Documentation

on:
  push:
    branches: [main]
    paths:
      - '10_DOCUMENTATION/**'
      - '2 - FOUNDATION/04_CORE/**/*.hpp'
      - '2 - FOUNDATION/04_CORE/**/*.h'

jobs:
  build-and-validate:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install mkdocs mkdocs-material mkdocs-minify-plugin
          npm install -g markdown-link-check cspell markdownlint-cli

      - name: Validate documentation
        run: |
          .\2 - FOUNDATION\03_INFRA\03_11_documentation_platform\03_11_05_documentation_automation\validate_docs.ps1 -All

      - name: Generate documentation
        run: |
          .\2 - FOUNDATION\03_INFRA\03_11_documentation_platform\03_11_05_documentation_automation\generate_docs.ps1 -Target all -Clean

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./var/docs

Scheduled Updates

# .github/workflows/docs-update.yml
name: Update Documentation

on:
  schedule:
    - cron: '0 2 * * 1'  # Weekly on Monday 2am

jobs:
  update:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3

      - name: Regenerate all docs
        run: |
          .\generate_docs.ps1 -Target all -Clean

      - name: Check for changes
        run: git diff --exit-code

      - name: Create PR if changes
        if: failure()
        uses: peter-evans/create-pull-request@v5
        with:
          title: "docs: regenerate documentation"
          body: "Automated documentation regeneration"
          branch: docs/auto-update

Changelog Automation

Using Conventional Commits

# Commit with type prefix
git commit -m "feat(dsp): add SIMD-optimized lowpass filter"
git commit -m "fix(core): resolve audio glitch on resize"
git commit -m "docs(api): improve AudioBuffer documentation"

Generate Changelog

# Using git-cliff
git cliff --tag v2.0.0 --output CHANGELOG.md

# Using standard-version
npm run release -- --release-as minor

See: changelog_automation.md

API Diff Generation

Compare Versions

# Generate API diff between v1.0.0 and v2.0.0
.\scripts\compare-api.ps1 -OldVersion v1.0.0 -NewVersion v2.0.0

Detect Breaking Changes

# Check if current changes are breaking
.\scripts\check-api-compat.ps1 -Base main -Current HEAD

See: api_diff_generation.md

Best Practices

Documentation Workflow

  1. Write documentation in markdown
  2. Validate locally with validate_docs.ps1
  3. Preview with generate_docs.ps1 -Serve
  4. Commit changes
  5. CI builds and validates
  6. Deploy automatically to hosting

Version Control

  • Commit source files (markdown, PlantUML, Doxyfile, mkdocs.yml)
  • Don't commit generated files (HTML, PNG from PlantUML)
  • Use Git LFS for large media files

Continuous Improvement

  • Monitor documentation coverage (% of APIs documented)
  • Track broken links (should be zero)
  • Review and update quarterly
  • Collect user feedback

Tooling Setup

Install Required Tools

Windows: 

# Doxygen
winget install doxygen

# Python + MkDocs
winget install Python.Python.3.11
pip install mkdocs mkdocs-material mkdocs-minify-plugin

# PlantUML
winget install plantuml

# Validation tools
npm install -g markdown-link-check cspell markdownlint-cli

# Changelog tools
npm install -g standard-version
cargo install git-cliff  # Or: winget install git-cliff

Verify Installation: 

doxygen --version
mkdocs --version
plantuml -version
markdown-link-check --version
cspell --version
markdownlint --version

Troubleshooting

Doxygen Fails

Error: Doxygen not found
Solution: winget install doxygen

MkDocs Build Errors

Error: docs_dir not found
Solution: Create 10_DOCUMENTATION/user_guide/ directory

PlantUML Not Generating

Error: PlantUML requires Java
Solution: winget install Oracle.JDK.21

Error: Too many 404 errors
Solution: Fix broken links or update .linkcheck config to ignore

Performance

Build Times (Typical)

  • API Docs (Doxygen): 30-60 seconds
  • User Docs (MkDocs): 5-10 seconds
  • Diagrams (PlantUML): 1-2 seconds per diagram

Optimization Tips

  • Use incremental builds (no -Clean)
  • Cache dependencies in CI
  • Parallelize diagram generation
  • Use mkdocs serve for live preview

References

Scripts

Guides

External Tools