Documentation Platform

Purpose

Complete documentation infrastructure for AudioLab, including configuration for API documentation, user guides, diagrams, multimedia content, and automation.

Overview

This directory contains the configuration and tooling for documentation, not the documentation content itself. Content lives in 10_DOCUMENTATION/.

Separation of Concerns

• Configuration (here): How to document (tools, templates, automation)
• Content (10_DOCUMENTATION): What to document (actual documentation)

Directory Structure

03_11_documentation_platform/
├── 03_11_00_api_documentation/      # Doxygen configuration
│   ├── Doxyfile                     # Doxygen config
│   ├── doxygen_theme/               # Custom theme
│   ├── doc_comments_guide.md        # How to write API docs
│   └── api_doc_standards.md         # Documentation requirements
│
├── 03_11_01_user_documentation/     # MkDocs configuration
│   ├── mkdocs.yml                   # MkDocs config
│   ├── docs_structure.md            # Content organization
│   └── markdown_style.md            # Writing standards
│
├── 03_11_02_architecture_diagrams/  # Diagram configuration
│   ├── plantuml_config.puml         # PlantUML theme
│   ├── diagram_types.md             # When to use what
│   └── mermaid_setup.md             # Mermaid in markdown
│
├── 03_11_03_multimedia_docs/        # Multimedia standards
│   ├── video_production_guide.md    # Tutorial videos
│   ├── screenshot_standards.md      # Screenshot guidelines
│   └── animation_tools.md           # GIF creation
│
├── 03_11_04_knowledge_management/   # Wiki and search
│   ├── wiki_structure.md            # Wiki organization
│   ├── notion_config.md             # Notion setup (optional)
│   └── search_optimization.md       # SEO and discoverability
│
└── 03_11_05_documentation_automation/ # Automation scripts
    ├── generate_docs.ps1            # Master generation script
    ├── validate_docs.ps1            # Quality validation
    ├── changelog_automation.md      # Auto-generate changelogs
    └── api_diff_generation.md       # Detect API changes

Quick Start

Prerequisites

# Install documentation tools
winget install doxygen plantuml

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

# Install validation tools (optional)
npm install -g markdown-link-check cspell markdownlint-cli

Generate All Documentation

cd "2 - FOUNDATION/03_INFRA/03_11_documentation_platform/03_11_05_documentation_automation"
.\generate_docs.ps1 -Target all -Clean

Validate Documentation

cd "2 - FOUNDATION/03_INFRA/03_11_documentation_platform/03_11_05_documentation_automation"
.\validate_docs.ps1 -All

View Generated Documentation

# API Reference (Doxygen)
start var\docs\api\html\index.html

# User Guide (MkDocs)
start var\docs\user\index.html

Documentation Types

1. API Reference (Doxygen)

Purpose: Auto-generated API documentation from code comments

Configuration: 03_11_00_api_documentation/ - Doxyfile with AudioLab settings - Custom theme with branding - Documentation standards

Output: var/docs/api/

How to Use: 1. Write documentation comments in C++ code 2. Follow doc_comments_guide.md standards 3. Run generate_docs.ps1 -Target api

2. User Documentation (MkDocs)

Purpose: User-facing guides, tutorials, and reference

Configuration: 03_11_01_user_documentation/ - mkdocs.yml with Material theme - Content structure guidelines - Markdown style guide

Output: var/docs/user/

How to Use: 1. Write markdown files in 10_DOCUMENTATION/user_guide/ 2. Follow markdown_style.md standards 3. Run generate_docs.ps1 -Target user 4. Or run mkdocs serve for live preview

3. Architecture Diagrams

Purpose: Visual documentation of system architecture

Configuration: 03_11_02_architecture_diagrams/ - PlantUML theme and macros - Mermaid setup for markdown - Diagram type guidelines

Output: SVG/PNG in 10_DOCUMENTATION/diagrams/

How to Use: 1. Create .puml files in 10_DOCUMENTATION/diagrams/ 2. Use !include plantuml_config.puml for consistent styling 3. Run generate_docs.ps1 -Target diagrams

4. Multimedia Content

Purpose: Videos, screenshots, animations

Configuration: 03_11_03_multimedia_docs/ - Video production standards - Screenshot guidelines - Animation/GIF creation

Storage: var/media/ (use Git LFS)

How to Use: 1. Follow guidelines for creating content 2. Store in appropriate subdirectory 3. Reference in documentation

5. Knowledge Management

Purpose: Collaborative knowledge sharing

Configuration: 03_11_04_knowledge_management/ - Wiki structure - Notion setup (optional) - Search optimization

Platforms: GitHub Wiki, Notion, Internal wiki

How to Use: 1. Create wiki pages using templates 2. Tag and categorize for discoverability 3. Link from formal documentation

6. Automation

Purpose: Automate documentation tasks

Configuration: 03_11_05_documentation_automation/ - Master generation script - Validation scripts - Changelog automation - API diff generation

How to Use: - Run scripts manually or in CI/CD - Integrate with git hooks - Schedule regular regeneration

Workflow

Writing Documentation

1. For API docs:
2. Add Doxygen comments to C++ code
3. Follow api_doc_standards.md

4. Run Doxygen to verify

5. For user docs:

6. Create markdown in 10_DOCUMENTATION/user_guide/
7. Follow markdown_style.md

8. Preview with mkdocs serve

9. For diagrams:

10. Create .puml or .mmd files
11. Use consistent styling

12. Generate with PlantUML

13. For multimedia:

14. Follow production guidelines
15. Optimize file sizes
16. Store in var/media/

Validation and Publishing

1. Validate locally:

   .\validate_docs.ps1 -All
   

2. Generate documentation:

   .\generate_docs.ps1 -Target all -Clean
   

3. Review output:

4. Check for warnings/errors
5. Verify links work

6. Test on different devices

7. Commit and push:

   git add .
   git commit -m "docs: update user guide"
   git push
   

8. CI/CD deploys:

9. Validates documentation
10. Generates docs
11. Deploys to hosting (GitHub Pages, etc.)

CI/CD Integration

GitHub Actions Example

name: Documentation

on:
  push:
    paths:
      - '10_DOCUMENTATION/**'
      - '2 - FOUNDATION/04_CORE/**/*.hpp'

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

      - name: Setup tools
        run: |
          pip install mkdocs mkdocs-material

      - name: Generate docs
        run: |
          cd "2 - FOUNDATION/03_INFRA/03_11_documentation_platform/03_11_05_documentation_automation"
          .\generate_docs.ps1 -Target all

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

Quality Standards

Mandatory (100% Compliance)

• All public APIs documented
• No broken links
• All images have alt text
• Builds without errors
• Spell check passes

Recommended (>80% Adoption)

• Code examples provided
• Diagrams for complex concepts
• Video tutorials for features
• Search-optimized content
• Mobile-friendly

Tools Reference

Tool	Purpose	Install
Doxygen	API documentation	winget install doxygen
MkDocs	User documentation	pip install mkdocs mkdocs-material
PlantUML	Diagrams	winget install plantuml
Git LFS	Large files	git lfs install
markdown-link-check	Link validation	npm install -g markdown-link-check
cspell	Spell checking	npm install -g cspell
markdownlint	Markdown linting	npm install -g markdownlint-cli

Documentation Content Location

Content is NOT in this directory. It's in:

10_DOCUMENTATION/
├── user_guide/           # MkDocs content
│   ├── index.md
│   ├── getting-started/
│   ├── user-guide/
│   └── tutorials/
│
├── diagrams/             # PlantUML/Mermaid diagrams
│   ├── architecture/
│   ├── classes/
│   └── sequences/
│
└── api/                  # API docs (generated by Doxygen)
    └── README.md

Source code comments (for Doxygen) are in:

2 - FOUNDATION/04_CORE/**/*.hpp
2 - FOUNDATION/05_MODULES/**/*.hpp

Maintenance

Regular Tasks

• Daily: CI builds and validates on push
• Weekly: Run validate_docs.ps1 manually
• Monthly: Review and update outdated content
• Quarterly: Full documentation audit

Version Updates

# Update Doxygen
winget upgrade doxygen

# Update MkDocs and plugins
pip install --upgrade mkdocs mkdocs-material mkdocs-minify-plugin

# Update PlantUML
winget upgrade plantuml

References

Subdirectory READMEs

• API Documentation (Doxygen)
• User Documentation (MkDocs)
• Architecture Diagrams
• Multimedia Docs
• Knowledge Management
• Documentation Automation

External Resources

• Doxygen Manual: https://www.doxygen.nl/manual/
• MkDocs Documentation: https://www.mkdocs.org/
• Material for MkDocs: https://squidfunk.github.io/mkdocs-material/
• PlantUML: https://plantuml.com/
• Keep a Changelog: https://keepachangelog.com/
• Conventional Commits: https://www.conventionalcommits.org/

Support

For questions: - API docs: See 03_11_00_api_documentation/README.md - User docs: See 03_11_01_user_documentation/README.md - Diagrams: See 03_11_02_architecture_diagrams/README.md - Automation: See 03_11_05_documentation_automation/README.md