docuguru 0.5.0

No project description provided

DocuGuru

Herramienta profesional para convertir documentos Markdown a PDF con estilos predefinidos y componentes personalizados.

Características

• Conversión de Markdown a PDF de alta calidad
• Página de portada automática con título, badge y fecha
• Tabla de contenidos generada automáticamente (H1, H2, H3)
• Soporte completo para títulos (h1-h6), tablas y listas
• Listas ordenadas con números estilizados en círculos
• Listas no ordenadas con checkmarks personalizados
• Componentes HTML personalizados (info-cards, timelines, summary-cards, etc.)
• Estilos profesionales predefinidos
• Diagramas Mermaid renderizados como imágenes en el PDF (requiere Playwright)
• Control de tamaño de diagramas Mermaid (small, medium, full)
• Optimizado para impresión en formato A4

Instalación

Producción (pip)

# Instalación base (sin diagramas Mermaid)
pip install docuguru

# Instalación con soporte para diagramas Mermaid
pip install docuguru[mermaid]
playwright install chromium

Sin Playwright instalado, los bloques Mermaid se muestran como código plano y docuguru imprime un warning en stderr. El resto de la conversión funciona normalmente.

Desarrollo (Poetry)

Solo core (sin Mermaid)

# Clonar el repositorio
git clone <repository-url>
cd docuguru

# Instalar dependencias base
poetry install

# Activar el entorno virtual
poetry shell

Con soporte Mermaid

# Clonar el repositorio
git clone <repository-url>
cd docuguru

# Instalar dependencias base + mermaid
poetry install --with mermaid

# Descargar el navegador Chromium (~300MB, se hace una vez)
poetry run playwright install chromium

# Activar el entorno virtual
poetry shell

Después de esto, los bloques ````mermaid` en tus Markdown se renderizan automáticamente como imágenes PNG de alta resolución en el PDF.

Ejecutar tests

poetry run pytest

Construir el paquete

poetry build

Uso

Inicializar una Propuesta

docuguru init

Crea un archivo propuesta.md con la estructura completa de una propuesta técnica de software, incluyendo secciones estándar y bloques HTML de ejemplo listos para editar.

Opciones:

• -o, --output <archivo>: Ruta del archivo Markdown a crear (por defecto: propuesta.md)
• -t, --title <título>: Título de la propuesta para el H1 del documento (por defecto: "Nombre del Proyecto")
• -f, --force: Sobrescribir el archivo si ya existe

Flujo recomendado:

# 1. Crear la estructura base
docuguru init -t "Sistema de Gestión"

# 2. Editar propuesta.md con el contenido del proyecto

# 3. Generar el PDF
docuguru convert propuesta.md -d "Junio 2026"

Comando Básico

docuguru convert documento.md

Esto generará un archivo documento.pdf en el mismo directorio.

Opciones Disponibles

docuguru convert documento.md [OPCIONES]

Opciones:

• -o, --output <archivo>: Especifica la ruta del archivo PDF de salida
• -t, --title <título>: Define el título del documento (por defecto se extrae del primer H1)
• --no-cover: No incluir página de portada
• --no-toc: No incluir tabla de contenidos
• --no-mermaid: No renderizar diagramas Mermaid (se muestran como código plano)
• -b, --badge <texto>: Texto del badge en la portada (por defecto: "Propuesta técnica")
• -d, --date <fecha>: Fecha para la portada (ej: "Diciembre 2025", por defecto: fecha actual)

Ejemplos

# Conversión básica
docuguru convert propuesta.md

# Con título personalizado y fecha
docuguru convert propuesta.md -t "Propuesta Técnica" -d "Enero 2025"

# Sin portada
docuguru convert documento.md --no-cover

# Sin renderizar Mermaid
docuguru convert documento.md --no-mermaid

# Especificar archivo de salida
docuguru convert documento.md -o salida/propuesta.pdf

# Con badge personalizado
docuguru convert documento.md -b "Informe Técnico"

Diagramas Mermaid

DocuGuru soporta diagramas escritos en sintaxis Mermaid directamente en el Markdown. Los diagramas se renderizan como imágenes PNG de alta resolución (2x DPI) que se incrustan en el PDF.

Tipos de diagrama soportados

Tipo	Sintaxis
Flowchart	graph TD / graph LR
Secuencia	sequenceDiagram
Clases	classDiagram
ER	erDiagram
Gantt	gantt
Estado	stateDiagram-v2
Arquitectura	graph LR con subgraph

Uso básico

```mermaid
graph TD
    A[Cliente] --> B[API Gateway]
    B --> C[Backend]
    C --> D[(Base de Datos)]
```

Control de tamaño

Los diagramas se ajustan automáticamente al ancho de la página (con max-width: 100%). Para controlar el tamaño, envuelve el bloque en un <div> con una clase de tamaño:

Pequeño (40% del ancho):

<div class="mermaid-diagram small">

```mermaid
graph TD
    A --> B

```

Mediano (65% del ancho):

<div class="mermaid-diagram medium">

```mermaid
sequenceDiagram
    A->>B: Request
    B-->>A: Response

```

Completo (100%, por defecto):

```mermaid
graph TD
    A --> B
```

Requisitos

Los diagramas Mermaid requieren Playwright y Chromium instalados. Ver la sección de instalación para detalles.

Documentación de Bloques Personalizados

Para ver todos los bloques HTML personalizados disponibles y cómo usarlos:

# Mostrar en consola
docuguru blocks

# Guardar en archivo
docuguru blocks -o bloques-documentacion.md

Componentes Personalizados Disponibles

1. Architecture Diagram

Diagrama de arquitectura centrado (imagen externa).

2. Info Card

Tarjeta informativa para fases o información destacada.

3. Timeline

Línea de tiempo vertical con items conectados.

4. Summary Cards

Tarjetas de resumen horizontales con valores destacados.

5. Support Packages

Tarjetas de paquetes de servicios lado a lado.

6. Styled List

Listas con checkmarks personalizados (✔).

7. Warranty Notice

Bloque de aviso o garantía destacado.

8. Mermaid Diagram

Diagramas renderizados desde código Mermaid con control de tamaño (small, medium, full).

Para más detalles y ejemplos de uso, ejecuta docuguru blocks.

Características de Markdown Soportadas

• Títulos: Todos los niveles (h1-h6)
• Tablas: Formato estándar de Markdown
• Listas ordenadas: Con numeración estilizada automática
• Listas no ordenadas: Con checkmarks personalizados
• Código: Bloques de código con syntax highlighting
• HTML personalizado: Componentes custom embebidos
• Diagramas Mermaid: Flowcharts, secuencia, clases, ER, Gantt, estado y más

Estilos Predefinidos

El proyecto incluye un conjunto completo de estilos CSS predefinidos que incluyen:

• Paleta de colores profesional (azules y grises)
• Tipografía Inter (con múltiples pesos)
• Gradientes y sombras modernas
• Optimización para impresión (page-breaks, márgenes)
• Diseño responsive

Estructura del Proyecto

docuguru/
├── src/
│   └── docuguru/
│       ├── __init__.py
│       ├── cli.py                  # Interfaz de línea de comandos
│       ├── markdon_to_html.py      # Conversor Markdown a HTML
│       ├── mermaid_processor.py    # Pre-procesador de bloques Mermaid
│       ├── mermaid_renderer.py     # Renderizador Mermaid → PNG (Playwright)
│       ├── html_to_pdf.py          # Generador de PDF
│       ├── default.py              # Estilos CSS predefinidos
│       ├── proposal_template.md    # Plantilla de propuesta técnica
│       └── blocks_documentation.md # Documentación de bloques HTML
├── tests/                      # Tests unitarios
├── pyproject.toml              # Configuración del proyecto
└── README.md                   # Este archivo