1.2.3. Programas

# doc_generator.py - Lee un archivo CSV con la definición de variables y genera documentación en Markdown
# Útil para estandarizar la documentación de programas PLC

import csv
import os
from datetime import datetime

class VariableDoc:
    """Clase para almacenar la información de una variable."""
    def __init__(self, nombre, direccion, tipo, rango, comentario):
        self.nombre = nombre
        self.direccion = direccion
        self.tipo = tipo
        self.rango = rango
        self.comentario = comentario

class ProgramDocumentation:
    """Genera documentación estructurada a partir de una lista de variables."""
    def __init__(self, proyecto, autor):
        self.proyecto = proyecto
        self.autor = autor
        self.variables = []      # lista de objetos VariableDoc
        self.bloques = []        # lista de diccionarios con info de bloques funcionales

    def cargar_variables_csv(self, archivo):
        """Carga variables desde un archivo CSV con columnas: Nombre,Dirección,Tipo,Rango,Comentario"""
        with open(archivo, 'r', encoding='utf-8') as f:
            reader = csv.DictReader(f)
            for row in reader:
                var = VariableDoc(
                    nombre=row['Nombre'],
                    direccion=row['Dirección'],
                    tipo=row['Tipo'],
                    rango=row['Rango'],
                    comentario=row['Comentario']
                )
                self.variables.append(var)
        print(f"✅ Cargadas {len(self.variables)} variables desde {archivo}")

    def agregar_bloque(self, nombre, descripcion, entradas, salidas):
        """Añade información de un bloque funcional."""
        self.bloques.append({
            "nombre": nombre,
            "descripcion": descripcion,
            "entradas": entradas,
            "salidas": salidas
        })

    def generar_markdown(self):
        """Genera el contenido en formato Markdown."""
        doc = f"# DOCUMENTACIÓN DEL PROGRAMA\n\n"
        doc += f"**Proyecto:** {self.proyecto}\n\n"
        doc += f"**Autor:** {self.autor}\n\n"
        doc += f"**Fecha:** {datetime.now().strftime('%d/%m/%Y')}\n\n"

        doc += "## 1. Lista de variables\n\n"
        doc += "| Nombre | Dirección | Tipo | Rango | Comentario |\n"
        doc += "|--------|-----------|------|-------|------------|\n"
        for v in self.variables:
            doc += f"| {v.nombre} | {v.direccion} | {v.tipo} | {v.rango} | {v.comentario} |\n"

        doc += "\n## 2. Bloques funcionales\n\n"
        for b in self.bloques:
            doc += f"### {b['nombre']}\n"
            doc += f"**Descripción:** {b['descripcion']}\n\n"
            doc += "**Entradas:**\n"
            for e in b['entradas']:
                doc += f"- {e}\n"
            doc += "**Salidas:**\n"
            for s in b['salidas']:
                doc += f"- {s}\n"
            doc += "\n"

        doc += "## 3. Requisitos de funcionamiento\n\n"
        doc += "- **Modos de operación:** Manual / Automático\n"
        doc += "- **Condiciones de seguridad:** Parada de emergencia prioritaria, enclavamientos.\n"
        doc += "- **Respuesta ante fallos:** Alarma, paso a modo seguro.\n\n"

        doc += "## 4. Control de versiones\n\n"
        doc += "| Versión | Fecha | Autor | Cambios realizados |\n"
        doc += "|---------|-------|-------|--------------------|\n"
        doc += "| 1.0 | - | - | Versión inicial |\n"

        return doc

    def guardar(self, archivo):
        with open(archivo, 'w', encoding='utf-8') as f:
            f.write(self.generar_markdown())
        print(f"✅ Documentación guardada en {archivo}")

# --- Ejemplo de uso ---
if __name__ == "__main__":
    # Crear objeto documentación
    prog_doc = ProgramDocumentation("Control de temperatura reactor R-101", "Ing. Laura Gómez")

    # Simular carga desde CSV (en realidad leeríamos un archivo real)
    # Por simplicidad, creamos algunas variables manualmente
    prog_doc.variables = [
        VariableDoc("Temp_Reactor", "%IW0", "INT", "0-27648", "Señal analógica PT100"),
        VariableDoc("Setpoint_Temp", "%MD10", "REAL", "0.0-200.0", "Consigna de temperatura (°C)"),
        VariableDoc("Salida_Calefactor", "%QW0", "INT", "0-27648", "Señal a variador de calefacción"),
        VariableDoc("Alta_Temperatura", "%M0.0", "BOOL", "0/1", "Alarma por sobrepasar límite")
    ]

    # Añadir información de bloques funcionales
    prog_doc.agregar_bloque(
        "FB_PID_Temp",
        "Control PID de temperatura del reactor",
        ["Setpoint (REAL)", "PV (REAL)", "Manual (BOOL)"],
        ["Output (REAL)", "Error (REAL)"]
    )
    prog_doc.agregar_bloque(
        "FC_Alarmas",
        "Gestión de alarmas de proceso",
        ["Temp_Alta (BOOL)", "Presion_Baja (BOOL)"],
        ["Alarma_General (BOOL)"]
    )

    # Generar y guardar
    prog_doc.guardar("documentacion_programa.md")

Este script lee una lista de variables (desde CSV o definida en código) y genera documentación estructurada en Markdown, incluyendo tabla de variables, descripción de bloques funcionales y control de versiones. Es una herramienta excelente para estandarizar la documentación de programas PLC.