AudioLab MkDocs - Sistema de Autodescubrimiento¶

Sistema profesional de documentación con descubrimiento automático de la estructura del repositorio.

🚀 Inicio Rápido¶

1. Instalación (Solo una vez)¶

cd 03_INFRA\03_11_documentation_platform\03_11_01_user_documentation
.\mkdocs-serve.ps1 -Action install

2. Iniciar Servidor¶

.\mkdocs-serve.ps1 -Open

¡Listo! El sistema: - ✅ Descubre automáticamente las 20 carpetas troncales - ✅ Lee todos los README.md del repositorio - ✅ Genera navegación jerárquica - ✅ Abre el navegador en http://127.0.0.1:8000

3. Añadir Documentación¶

Simplemente crea o edita archivos markdown en cualquier lugar del repositorio:

# En cualquier carpeta, crea o edita README.md
05_MODULES/05_XX_mi_modulo/README.md

# Se convierte automáticamente en página índice de esa sección

Guarda → Recarga navegador → ¡Aparece automáticamente!

✨ Características¶

Autodescubrimiento Total¶

Cero configuración manual: La navegación se genera del árbol de carpetas
20 carpetas troncales: De 01_RESEARCH a 20_MIGRATIONS
Profundidad infinita: Descubre subcarpetas recursivamente
README.md = índice: Cada README se convierte en página índice de sección

Sistema Profesional¶

MkDocs Material: Tema moderno y responsive
Búsqueda completa: Con sugerencias y resaltado
Modo oscuro/claro: Preferencia del usuario
Git integrado: Muestra fechas de actualización y autores
Optimizado: Build rápido y output minificado

🔧 Cómo Funciona¶

El Proceso¶

Build time: Al ejecutar mkdocs serve o mkdocs build
Script automático: scripts/gen_nav.py se ejecuta
Escaneo del repo: Recorre las 20 carpetas principales
Descubrimiento: Encuentra todos los README.md y .md
Copia virtual: Copia archivos a directorio docs/ virtual
Generación nav: Crea SUMMARY.md con estructura jerárquica
Renderizado: MkDocs lee SUMMARY.md y genera el sitio

Arquitectura¶

Repositorio                        MkDocs (Virtual)
===========                        ================
01_RESEARCH/                  →    docs/01_RESEARCH/
  README.md                   →      index.md
  01_00_market/               →    docs/01_RESEARCH/01_00_market/
    README.md                 →      index.md
    analysis.md               →      analysis.md

03_INFRA/                     →    docs/03_INFRA/
  README.md                   →      index.md
  03_11_documentation/        →    docs/03_INFRA/03_11_documentation/
    README.md                 →      index.md

📋 Comandos¶

Script PowerShell (Recomendado)¶

# Instalar dependencias
.\mkdocs-serve.ps1 -Action install

# Servidor desarrollo (puerto 8000)
.\mkdocs-serve.ps1

# Servidor con puerto personalizado y abrir navegador
.\mkdocs-serve.ps1 -Port 9000 -Open

# Build estático
.\mkdocs-serve.ps1 -Action build

# Limpiar archivos generados
.\mkdocs-serve.ps1 -Action clean

# Ayuda completa
.\mkdocs-serve.ps1 -Action help

MkDocs Directo¶

# Servidor desarrollo
mkdocs serve

# Build
mkdocs build

# Deploy a GitHub Pages
mkdocs gh-deploy

📚 Workflows¶

Documentar Nueva Funcionalidad¶

Ve a la carpeta apropiada: 05_MODULES/05_24_mi_feature/
Crea/edita README.md con descripción general
Añade docs detallados: api.md, examples.md, etc.
Guarda → ¡Aparece automáticamente en navegación!

Crear Nuevo Módulo¶

Crea carpeta: 05_MODULES/05_XX_nuevo_modulo/
Añade README.md con descripción del módulo
Añade documentación: implementation.md, tests.md
Refresca navegador → Nueva sección visible

Reorganizar Documentación¶

Mueve/renombra carpetas en el repositorio
Actualiza README.md si es necesario
Rebuild → Navegación se actualiza automáticamente

¡Sin editar configuración manualmente!

🎨 Personalización¶

Cambiar Profundidad de Descubrimiento¶

Edita scripts/gen_nav.py:

# Línea 236
process_folder(folder_path, nav, depth=0, max_depth=5)  # Cambiar max_depth

Ignorar Carpetas Adicionales¶

Edita scripts/gen_nav.py:

# Línea 35
SKIP_FOLDERS = {
    '__LEGAZY',
    '.git',
    # Añade más aquí
    'mi_carpeta_privada',
}

Cambiar Colores del Tema¶

Edita mkdocs.yml:

theme:
  palette:
    primary: indigo  # blue, green, red, etc.
    accent: blue

🔍 Plugins Profesionales¶

El sistema usa plugins de nivel enterprise:

mkdocs-gen-files: Ejecuta script Python en build time
mkdocs-literate-nav: Navegación desde archivos descubiertos
mkdocs-section-index: README.md como índices clicables
mkdocs-material: Tema Material Design moderno
mkdocs-git-revision-date: Fechas de última actualización
mkdocs-git-authors: Muestra contribuidores por página
mkdocs-minify: Optimiza archivos de salida

🐛 Resolución de Problemas¶

"Module not found"¶

.\mkdocs-serve.ps1 -Action install

Páginas No Aparecen¶

Verifica que el archivo termine en .md
Chequea que la carpeta no esté en SKIP_FOLDERS
Asegúrate de que el archivo tiene encabezado H1 (#)

Servidor No Inicia¶

# Verificar Python (requiere 3.8+)
python --version

# Usar puerto diferente
.\mkdocs-serve.ps1 -Port 9000

🚀 CI/CD¶

GitHub Actions¶

name: Documentation

on:
  push:
    branches: [main]
    paths:
      - '**/*.md'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # Para plugin git-revision-date

      - uses: actions/setup-python@v4
        with:
          python-version: 3.x

      - run: |
          cd 03_INFRA/03_11_documentation_platform/03_11_01_user_documentation
          pip install -r requirements.txt
          mkdocs gh-deploy --force

📖 Estructura de Archivos¶

03_11_01_user_documentation/
├── mkdocs.yml              # Configuración MkDocs
├── requirements.txt        # Dependencias Python
├── mkdocs-serve.ps1       # Script helper
├── scripts/
│   └── gen_nav.py         # ⭐ Script de autodescubrimiento
├── docs/                  # Generado automáticamente
│   ├── index.md          # Página principal
│   ├── SUMMARY.md        # Navegación auto-generada
│   └── [estructura repo] # Espejo del repositorio
└── README.md             # Este archivo

🎯 Por Qué Este Enfoque¶

Usamos mkdocs-gen-files + literate-nav en lugar de alternativas porque:

✅ Mantenimiento cero: Sin configuración manual de navegación
✅ Escalable: Funciona con repos de cualquier tamaño
✅ Profesional: Usado por proyectos grandes (mkdocstrings, etc.)
✅ Flexible: Fácil personalizar lógica de descubrimiento
✅ Rápido: Solo procesa archivos modificados en desarrollo

Alternativas No Usadas¶

❌ Symlinks: Frágiles, dependientes de OS
❌ Nav manual: Requiere actualizaciones constantes
❌ awesome-pages solo: Requiere archivos .pages en todas partes
❌ monorepo-plugin: Excesivo para nuestra estructura

Nuestro enfoque es el punto óptimo entre automatización y control.

📚 Recursos¶

📍 Ubicaciones¶

Config: 03_INFRA/03_11_documentation_platform/03_11_01_user_documentation/
Output: var/docs/user/
Contenido: En todo el repositorio (todos los README.md y .md)

Estado: Listo para Producción Mantenimiento: Cero (autodescubrimiento automático) Última Actualización: 2025-10-16