Living Documentation: Auto-Generar Documentación desde Código y Pruebas

# Ejemplo: Flujo GitHub Actions para generación de documentación
name: Generate Living Documentation

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  generate-docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

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

      - name: Instalar dependencias
        run: |
          pip install sphinx sphinx-rtd-theme
          pip install -r requirements.txt

      - name: Generar docs API con Sphinx
        run: |
          cd docs
          sphinx-apidoc -f -o source/api ../src
          make html

      - name: Ejecutar pruebas BDD y generar reportes Cucumber
        run: |
          pytest --cucumber-json=cucumber.json
          node generate-cucumber-report.js

      - name: Generar especificación OpenAPI
        run: |
          python generate_openapi.py > openapi.yaml

      - name: Desplegar documentación
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_build/html

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
from typing import List, Optional
from enum import Enum

app = FastAPI(
    title="API E-commerce",
    description="API para gestión de productos, pedidos y clientes",
    version="2.0.0",
    docs_url="/api/docs",
    redoc_url="/api/redoc"
)

class ProductCategory(str, Enum):
    """Enumeración de categoría de producto"""
    ELECTRONICS = "electronics"
    CLOTHING = "clothing"
    BOOKS = "books"

class Product(BaseModel):
    """Modelo de producto con validación"""
    id: Optional[int] = Field(None, description="Identificador único de producto")
    name: str = Field(..., min_length=1, max_length=200, description="Nombre del producto")
    description: str = Field(..., description="Descripción detallada del producto")
    price: float = Field(..., gt=0, description="Precio del producto en USD")
    category: ProductCategory = Field(..., description="Categoría del producto")
    in_stock: bool = Field(True, description="Estado de disponibilidad")

    class Config:
        schema_extra = {
            "example": {
                "id": 123,
                "name": "Laptop Pro 15",
                "description": "Laptop de alto rendimiento con 16GB RAM",
                "price": 1299.99,
                "category": "electronics",
                "in_stock": True
            }
        }

@app.get(
    "/products",
    response_model=List[Product],
    summary="Listar todos los productos",
    description="Recuperar lista paginada de todos los productos en el catálogo",
    response_description="Lista de productos con metadatos de paginación"
)
async def list_products(
    skip: int = Field(0, ge=0, description="Número de registros a omitir"),
    limit: int = Field(10, ge=1, le=100, description="Máximo de registros a devolver"),
    category: Optional[ProductCategory] = Field(None, description="Filtrar por categoría")
):
    """
    Listar productos con filtrado opcional.

    - **skip**: Desplazamiento de paginación (predeterminado: 0)
    - **limit**: Tamaño de página, máx 100 (predeterminado: 10)
    - **category**: Filtro opcional de categoría

    Devuelve una lista de productos que coinciden con los criterios.
    """
    pass

@app.post(
    "/products",
    response_model=Product,
    status_code=201,
    summary="Crear nuevo producto",
    description="Agregar un nuevo producto al catálogo",
    responses={
        201: {"description": "Producto creado exitosamente"},
        400: {"description": "Datos de producto inválidos"},
        409: {"description": "Producto ya existe"}
    }
)
async def create_product(product: Product):
    """
    Crear un nuevo producto en el catálogo.

    Campos requeridos:
    - name: Nombre del producto (1-200 caracteres)
    - description: Descripción detallada
    - price: Precio en USD (debe ser positivo)
    - category: Uno de: electronics, clothing, books

    Devuelve el producto creado con ID asignado.
    """
    pass

# features/checkout.feature
Feature: Proceso de Compra del Carrito
  Como cliente
  Quiero completar compras a través de un proceso de pago optimizado
  Para que pueda comprar productos de forma rápida y segura

  Background:
    Given el catálogo de productos contiene:
      | id | name           | price  | stock |
      | 1  | Laptop Pro 15  | 1299.99| 10    |
      | 2  | Mouse Inalámbrico | 29.99  | 50    |
    And estoy conectado como "john@example.com"

  @critical @payment
  Scenario: Pago exitoso con tarjeta de crédito
    Given he agregado los siguientes artículos a mi carrito:
      | product_id | quantity |
      | 1          | 1        |
      | 2          | 2        |
    When procedo al pago
    And ingreso dirección de envío:
      | field       | value              |
      | street      | Calle Principal 123|
      | city        | Barcelona          |
      | state       | Cataluña           |
      | postal_code | 08001              |
    And selecciono método de entrega "Envío Estándar"
    And pago con tarjeta de crédito
    Then el pedido debe ser confirmado
    And debo recibir un email de confirmación
    And el monto total cobrado debe ser $1,369.97
    And mi carrito debe estar vacío

class PaymentProcessor:
    """
    Maneja el procesamiento de pagos para varios métodos de pago.

    Esta clase proporciona una interfaz unificada para procesar pagos
    a través de diferentes proveedores (Stripe, PayPal, etc.).

    Attributes:
        provider (str): Nombre del proveedor de pasarela de pago
        api_key (str): Clave de autenticación para el proveedor
        timeout (int): Tiempo de espera de solicitud en segundos

    Example:
        >>> processor = PaymentProcessor('stripe', api_key='sk_test_...')
        >>> result = processor.charge(amount=99.99, currency='USD')
        >>> print(result.status)
        'succeeded'
    """

    def charge(self, amount, currency, card_token, idempotency_key=None):
        """
        Cobrar un método de pago.

        Args:
            amount (float): Monto a cobrar en la moneda especificada
            currency (str): Código de moneda ISO de tres letras
            card_token (str): Identificador de tarjeta tokenizado
            idempotency_key (str, optional): Clave única para prevenir cargos duplicados

        Returns:
            PaymentResult: Objeto conteniendo detalles de transacción

        Raises:
            InvalidAmountError: Si el monto es negativo o cero
            CardDeclinedError: Si el pago es rechazado por el emisor
            NetworkError: Si falla conexión con proveedor de pago
        """
        pass

# ADR-005: Adoptar Enfoque Living Documentation

## Estado
Aceptado

## Contexto
Nuestro equipo lucha con documentación que se vuelve obsoleta rápidamente.
Los desarrolladores raramente actualizan docs después de cambios de código.

## Decisión
Adoptaremos principios de Living Documentation:
1. Generar docs API desde anotaciones de código
2. Usar escenarios BDD como documentación ejecutable
3. Auto-generar reportes de prueba en pipeline CI/CD
4. Almacenar ADRs en control de versiones

## Consecuencias

### Positivas
- Documentación siempre refleja implementación actual
- Reducción de mantenimiento manual
- Fuente única de verdad (código)
- Documentación se vuelve verificable

### Negativas
- Esfuerzo inicial de configuración de herramientas
- El equipo necesita capacitación

# tests/test_documentation.py
import pytest
from pathlib import Path
import re

def test_all_code_examples_are_valid():
    """Asegurar que todos los ejemplos de código Python sean sintácticamente correctos"""
    docs_path = Path("docs")

    for doc_file in docs_path.rglob("*.md"):
        content = doc_file.read_text()
        code_blocks = re.findall(r'```python\n(.*?)\n```', content, re.DOTALL)

        for i, code in enumerate(code_blocks):
            try:
                compile(code, f'{doc_file}:block-{i}', 'exec')
            except SyntaxError as e:
                pytest.fail(f"Código Python inválido en {doc_file}: {e}")

def test_api_endpoints_documented():
    """Asegurar que todos los endpoints API tengan documentación OpenAPI"""
    from app import app

    openapi = app.openapi()
    documented = set(openapi['paths'].keys())
    actual = {route.path for route in app.routes if hasattr(route, 'path')}

    undocumented = actual - documented
    assert not undocumented, f"Endpoints sin documentar: {undocumented}"