Skip to content

05_02_10 - Documentation Integration

📋 Descripción General

Generación automática de documentación técnica del grafo de dependencias. Produce documentación en múltiples formatos (Markdown, HTML, Doxygen) directamente desde el catálogo, manteniéndola siempre sincronizada con el código.

🎯 Objetivos

  1. Auto-Generate Docs desde el catálogo JSON
  2. Multiple Formats - Markdown, HTML, Doxygen, MkDocs
  3. Module Pages individuales con dependencias visualizadas
  4. Hierarchy Overview con diagramas Mermaid
  5. Always Up-to-Date con integración a Live Monitor

🏗️ Arquitectura

DocumentationGenerator
├── MarkdownGenerator (GitHub/GitLab)
├── HtmlGenerator (Static sites)
├── DoxygenIntegration (API docs)
├── MkDocsGenerator (Material theme)
└── TemplateEngine (customizable templates)

📚 Formatos de Salida

1. Markdown (GitHub/GitLab)

# Module: Biquad Filter

**ID**: `filter_biquad`
**Level**: L1_ATOM
**Category**: FILTER
**Status**: STABLE

## Performance

- **CPU**: 50 cycles
- **Latency**: 0 samples

## Dependencies

This module depends on:
- `mul` (L0_KERNEL) - Multiply operation

## Dependents

Used by:
- `voice_mono` (L2_CELL)
- `effect_reverb` (L2_CELL)

## Dependency Graph

```mermaid
graph TD
    filter_biquad --> mul
    voice_mono --> filter_biquad
    effect_reverb --> filter_biquad

### 2. HTML (Static Site)

```html
<!DOCTYPE html>
<html>
<head>
    <title>Biquad Filter - Module Documentation</title>
    <link rel="stylesheet" href="styles.css">
</head>
<body>
    <nav><!-- Breadcrumbs --></nav>

    <main>
        <h1>Biquad Filter</h1>

        <div class="metadata">
            <span class="badge level-l1">L1_ATOM</span>
            <span class="badge category">FILTER</span>
            <span class="badge status-stable">STABLE</span>
        </div>

        <section class="performance">
            <h2>Performance Metrics</h2>
            <div class="metrics">
                <div class="metric">
                    <span class="label">CPU</span>
                    <span class="value">50 cycles</span>
                </div>
                <div class="metric">
                    <span class="label">Latency</span>
                    <span class="value">0 samples</span>
                </div>
            </div>
        </section>

        <section class="dependencies">
            <h2>Dependencies</h2>
            <ul>
                <li><a href="mul.html">mul</a> (L0_KERNEL)</li>
            </ul>
        </section>

        <section class="graph">
            <h2>Dependency Graph</h2>
            <div id="graph-container"></div>
            <script src="render-graph.js"></script>
        </section>
    </main>
</body>
</html>

3. Doxygen Integration

/**
 * @defgroup filter_biquad Biquad Filter
 * @ingroup L1_ATOM
 * @brief Second-order IIR filter with configurable coefficients
 *
 * @par Performance
 * - CPU: 50 cycles
 * - Latency: 0 samples
 *
 * @par Dependencies
 * - @ref mul (L0_KERNEL)
 *
 * @par Dependents
 * - @ref voice_mono (L2_CELL)
 * - @ref effect_reverb (L2_CELL)
 *
 * @dot
 * digraph dependencies {
 *     filter_biquad -> mul;
 *     voice_mono -> filter_biquad;
 *     effect_reverb -> filter_biquad;
 * }
 * @enddot
 */

4. MkDocs (Material Theme)

# mkdocs.yml
site_name: Audio Lab - Module Documentation
theme:
  name: material
  palette:
    primary: indigo
    accent: blue

nav:
  - Home: index.md
  - Hierarchy:
    - L0_KERNEL: hierarchy/l0_kernel.md
    - L1_ATOM: hierarchy/l1_atom.md
    - L2_CELL: hierarchy/l2_cell.md
    - L3_ENGINE: hierarchy/l3_engine.md
  - Modules:
    - Filters: modules/filters.md
    - Oscillators: modules/oscillators.md
    - Effects: modules/effects.md
  - API Reference: api/

🔧 Uso Básico

Generación Simple

#include "doc_generator.hpp"

using namespace audio_lab::dependency_graph;

// Cargar grafo
GraphBuilder builder;
builder.load_from_catalog("catalog.json");
Graph graph = builder.build();

// Generar documentación Markdown
MarkdownGenerator md_gen;
md_gen.generate_module_docs(graph, "docs/modules/");
md_gen.generate_index(graph, "docs/README.md");
md_gen.generate_hierarchy_overview(graph, "docs/HIERARCHY.md");

std::cout << "✅ Documentation generated in docs/\n";

Generación Completa (Todos los Formatos)

#include "doc_generator.hpp"

DocumentationGenerator doc_gen(graph);

// Configurar salidas
doc_gen.set_output_directory("docs/");
doc_gen.enable_markdown(true);
doc_gen.enable_html(true);
doc_gen.enable_doxygen(true);

// Generar
doc_gen.generate_all();

std::cout << "📚 Complete documentation generated:\n";
std::cout << "  - Markdown: docs/markdown/\n";
std::cout << "  - HTML: docs/html/\n";
std::cout << "  - Doxygen: docs/doxygen/\n";

Con Live Monitor (Auto-Update)

#include "doc_generator.hpp"
#include "live_monitor.hpp"

LiveMonitor monitor("catalog.json");

monitor.on_change([](const GraphChange& change) {
    // Regenerar documentación automáticamente
    MarkdownGenerator md_gen;
    md_gen.generate_all(monitor.get_current_graph(), "docs/");

    std::cout << "📚 Documentation updated\n";
});

monitor.start();

📄 Tipos de Documentos

1. Module Pages (Por Módulo)

Contenido: - Metadata (ID, level, category, status) - Performance metrics (CPU, latency) - Version info - Dependencies (directas) - Dependents (quién lo usa) - Dependency graph (visualización local) - Usage examples (si disponibles)

Archivo: modules/<module_id>.md o .html

2. Hierarchy Overview

Contenido: - Resumen de cada nivel jerárquico - Módulos por nivel - Reglas de dependencia - Diagrama Mermaid de la jerarquía completa - Estadísticas (cantidad por nivel)

Archivo: HIERARCHY.md

3. Category Index

Contenido: - Módulos agrupados por categoría - FILTER, OSC, EFFECT, VOICE, etc. - Breve descripción de cada categoría - Links a módulos individuales

Archivo: CATEGORIES.md

4. Dependency Matrix

Contenido: - Matriz de dependencias (quién depende de quién) - Tabla HTML interactiva - Heatmap de conectividad - Bottleneck highlights

Archivo: DEPENDENCIES.md o dependencies.html

5. Index/Landing Page

Contenido: - Overview del proyecto - Quick stats (total modules, edges, density) - Quick links a secciones - Getting started guide - Diagrama general del grafo

Archivo: index.md o index.html

6. API Reference (Doxygen)

Contenido: - Integración con Doxygen existente - Grupos por módulo - Cross-references entre módulos - DOT graphs embebidos

Archivo: Doxyfile updates

🎨 Templates Personalizables

Template Engine

// Template con placeholders
std::string module_template = R"(
# Module: {{module.label}}

**ID**: `{{module.id}}`
**Level**: {{module.level}}
**Category**: {{module.category}}

## Performance

- **CPU**: {{module.cpu_cycles}} cycles
- **Latency**: {{module.latency_samples}} samples

{{#if dependencies}}
## Dependencies

{{#each dependencies}}
- [{{this.label}}]({{this.id}}.md) ({{this.level}})
{{/each}}
{{/if}}
)";

// Usar template
TemplateEngine engine;
engine.register_template("module", module_template);

std::string rendered = engine.render("module", module_data);

Templates Incluidos

1. Default Markdown: - Simple, compatible con GitHub - Mermaid diagrams - Badge styles con emojis

2. GitHub Pages: - Jekyll front matter - Navigation sidebar - Search-friendly

3. GitLab Pages: - GitLab Markdown extensions - Collapsible sections - Emoji shortcuts

4. MkDocs Material: - Material theme compatible - Admonitions - Code blocks con syntax highlighting

5. Docusaurus: - MDX format - Interactive components - Versioning support

🔍 Generación Automática

From Catalog Metadata

{
    "id": "filter_biquad",
    "label": "Biquad Filter",
    "documentation": {
        "description": "Second-order IIR filter",
        "usage_example": "auto filter = BiquadFilter(coeffs);",
        "see_also": ["filter_onepole", "filter_svf"],
        "references": [
            "https://en.wikipedia.org/wiki/Digital_biquad_filter"
        ]
    }
}

Genera: - Description section - Usage examples code block - See Also links - External References

From Code Comments

/**
 * @audio_lab_module filter_biquad
 * @brief Second-order IIR filter with configurable coefficients
 *
 * Implements a biquadratic filter (two poles, two zeros) commonly
 * used in audio DSP for EQ, filtering, and tone shaping.
 *
 * @example
 * ```cpp
 * BiquadFilter filter;
 * filter.set_lowpass(440.0f, 0.7f);
 * float output = filter.process(input);
 * ```
 */

Extrae: - Brief description - Detailed description - Code examples - Parámetros (si están documentados)

📊 Visualizaciones Incluidas

1. Module Dependency Graph (Local)

graph TD
    filter_biquad[Biquad Filter<br/>50 CPU]
    mul[Multiply<br/>1 CPU]
    voice[Voice<br/>150 CPU]

    filter_biquad --> mul
    voice --> filter_biquad

    style filter_biquad fill:#00AA44
    style mul fill:#0066CC
    style voice fill:#FFAA00

2. Hierarchy Diagram

graph TB
    subgraph L3_ENGINE
        engine[Synth Engine]
    end

    subgraph L2_CELL
        voice[Voice]
        effect[Effect]
    end

    subgraph L1_ATOM
        osc[Oscillator]
        filter[Filter]
    end

    subgraph L0_KERNEL
        mul[Multiply]
        add[Add]
    end

    engine --> voice
    engine --> effect
    voice --> osc
    voice --> filter
    effect --> filter
    filter --> mul

3. Category Distribution (Pie Chart)

## Module Distribution by Category

| Category | Count | Percentage |
|----------|-------|------------|
| FILTER   | 12    | 25%        |
| OSC      | 8     | 17%        |
| EFFECT   | 15    | 31%        |
| VOICE    | 6     | 13%        |
| OTHER    | 7     | 14%        |

4. Performance Heatmap

## CPU Usage by Module

| Module         | CPU  | ████████████ |
|----------------|------|--------------|
| Engine         | 300  | ████████████ |
| Voice          | 150  | ██████       |
| Effect         | 80   | ███          |
| Filter         | 50   | ██           |
| Oscillator     | 30   | █            |

🔗 Integración con Herramientas

MkDocs Integration

# Generar docs
./doc_generator --format mkdocs --output docs/

# Servir localmente
cd docs
mkdocs serve

# Build para producción
mkdocs build

Doxygen Integration

// Actualizar Doxyfile automáticamente
DoxygenIntegration doxygen;
doxygen.update_doxyfile(graph, "Doxyfile");
doxygen.add_module_groups(graph);
doxygen.generate_dot_graphs(graph);

// Ejecutar Doxygen
system("doxygen Doxyfile");

Sphinx Integration

# conf.py extension
extensions = ['audiolab_graph_docs']

# Genera automáticamente
audiolab_graph_docs_catalog = 'catalog.json'
audiolab_graph_docs_output = 'modules/'

GitHub Actions (Auto-Deploy)

name: Generate Docs

on:
  push:
    paths:
      - 'catalog.json'

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Generate Documentation
        run: |
          ./doc_generator --format markdown --output docs/

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

📐 Casos de Uso Prácticos

1. Onboarding de Nuevos Desarrolladores

Problema: Nuevos devs no conocen la arquitectura.

Solución: 

// Generar "Getting Started" guide
DocumentationGenerator doc_gen(graph);
doc_gen.generate_onboarding_guide("docs/GETTING_STARTED.md");

Contenido: - Hierarchy explanation - Module naming conventions - Dependency rules - Common patterns - Where to find things

2. PR Reviews con Context

Problema: Reviewers no ven impacto de cambios.

Solución: 

// En CI/CD, generar diff de docs
auto old_docs = generate_docs(old_graph);
auto new_docs = generate_docs(new_graph);

auto diff = compute_doc_diff(old_docs, new_docs);
post_to_pr_comment(diff);

Output en PR: 

## Documentation Changes

### Modified Modules
- `filter_biquad`: CPU increased 50 → 60 (+20%)

### New Dependencies
- `voice_mono` now depends on `envelope_adsr`

### Impact Analysis
This change affects 12 modules upstream.

3. Architecture Decision Records (ADRs)

Problema: Decisiones de arquitectura no documentadas.

Solución: 

// Generar ADR desde cambios estructurales
if (change.structural.topology_changed) {
    generate_adr(
        "ADR-" + timestamp,
        "Add dependency: " + edge.source + " -> " + edge.target,
        "Justification: ...",
        graph
    );
}

4. Module Catalog para Reutilización

Problema: Devs re-implementan módulos existentes.

Solución: 

// Generar catálogo searchable
doc_gen.generate_searchable_catalog("docs/catalog.json");

Features: - Full-text search - Filter by category/level - Sort by CPU/latency - Quick links to source

5. Dependency Audit Reports

Problema: Necesitas auditar dependencias para compliance.

Solución: 

// Generar audit report
AuditReportGenerator audit(graph);
audit.include_licenses(true);
audit.include_authors(true);
audit.include_versions(true);

audit.generate_pdf("audit_report.pdf");

🎭 Styling & Theming

CSS Themes Incluidos

1. GitHub Style: 

.module-badge {
    background: #0366d6;
    color: white;
    padding: 2px 6px;
    border-radius: 3px;
}

2. Dark Mode: 

@media (prefers-color-scheme: dark) {
    body {
        background: #0d1117;
        color: #c9d1d9;
    }
}

3. Print-Friendly: 

@media print {
    .navigation { display: none; }
    .graph { page-break-inside: avoid; }
}

Mermaid Themes

%%{init: {'theme':'dark', 'themeVariables': {
  'primaryColor': '#BB2528',
  'primaryTextColor': '#fff',
  'primaryBorderColor': '#7C0000'
}}}%%

🚀 Performance

Generación Incremental

// Solo regenerar módulos modificados
if (change.nodes_modified.size() < 10) {
    for (const auto& node_change : change.nodes_modified) {
        regenerate_module_page(node_change.id);
    }
} else {
    // Full rebuild si muchos cambios
    regenerate_all();
}

Caching

// Cache de rendered templates
TemplateCache cache;

if (cache.has("module", module.id)) {
    return cache.get("module", module.id);
}

auto rendered = engine.render("module", module);
cache.set("module", module.id, rendered);

Parallel Generation

// Generar módulos en paralelo
std::vector<std::future<void>> futures;

for (const auto& [id, node] : graph.get_nodes()) {
    futures.push_back(std::async([&]() {
        generate_module_page(node);
    }));
}

for (auto& future : futures) {
    future.get();
}

📈 Métricas de Documentación

struct DocumentationStats {
    size_t modules_documented{0};
    size_t modules_total{0};
    size_t pages_generated{0};
    size_t total_size_kb{0};

    double coverage() const {
        return 100.0 * modules_documented / modules_total;
    }
};

🔧 Configuración

struct DocGeneratorConfig {
    std::filesystem::path output_dir{"docs/"};

    // Formatos habilitados
    bool enable_markdown{true};
    bool enable_html{false};
    bool enable_doxygen{false};

    // Contenido
    bool include_graphs{true};
    bool include_performance{true};
    bool include_source_links{false};

    // Estilo
    std::string theme{"default"};
    std::string mermaid_theme{"default"};

    // Templates
    std::string template_dir{"templates/"};
};

Parte de: 05_02_DEPENDENCY_GRAPH - Dependency Graph Visualizer Requiere: graph.hpp, template engine Exporta: doc_generator.hpp