Generador de Documentación de Ontología SimpleOntoDoc

Generador de Documentación Estática para Ontologías: Implementación y Aplicaciones

SimpleOntoDoc es una herramienta para crear sitios web estáticos que documentan ontologías. Una ontología describe un área temática mediante clases, atributos y las relaciones entre ellos. El proyecto está orientado hacia modelos internos de empresas y estándares como CIM (IEC61970), pero tiene aplicaciones más amplias.

La herramienta genera navegación, diagramas, tablas de propiedades y funcionalidad de búsqueda. Admite el análisis de descripciones de esquemas JSON, renderiza diagramas UML con PlantUML y utiliza Bootstrap para la interfaz.

Estructura del Sitio Generado

La página de inicio presenta mosaicos para acceso rápido: Clases, Enumeraciones, Primitivos, Tipos de Datos, Compuestos. Cada mosaico filtra entidades por tipo. El encabezado incluye una búsqueda que no distingue entre mayúsculas y minúsculas por nombres y descripciones.

La pestaña Entidades muestra una tabla de todas las entidades con búsqueda interactiva. Las filas son clicables y conducen a páginas de clases.

En una página de clase (ejemplo: PowerSystemResource):

• Descripción y diagrama UML de la jerarquía de herencia + relaciones salientes.
• Tabla de propiedades con IDs clicables.
• Bloque de resumen: navegación a padres, hijos y uso como tipo de dato.
• Tabla de referencia: propiedades de otras clases donde esta clase es el tipo.
• Tabla de clases hijas.

Los diagramas son interactivos: panzoom para navegación, los nodos son clicables.

Una página de propiedad (ejemplo: PowerSystemResource.Controls) incluye una descripción, resumen y navegación.

Aplicaciones en Proyectos

La herramienta es adecuada para dominios con estructuras similares a UML: clases, herencia, composición. Describe la ontología en JSON (API model.py), luego genera el sitio.

Casos de uso:

• Documentación de entidades de negocio en un servicio (50+ clases).
• Lenguaje común entre desarrolladores, analistas y autores de requisitos.
• CI/CD: generar el sitio cuando cambia el JSON en Git.
• Base para generación de código o exportación.

Separa la ontología de la lógica de negocio en los requisitos.

Tecnologías Utilizadas

• C# / .NET 9: base de la aplicación.
• PlantUML: renderiza diagramas UML a través de un servidor temporal.
• RazorLight: plantillas de páginas.
• Bootstrap 5: diseño frontend.

El script de publicación construye un contenedor Docker con Nginx.

Comparación con Alternativas

| Herramienta | Ventajas | Desventajas |

|------------|-------|--------|

| ontology.tno.nl | Sitios listos para CIM | Sin código fuente, no adaptado para GOST |

| Widoco | Soporte OWL | Página única, información superflua, diseño |

| Ontospy | Árbol de herencia | Requiere modificaciones para JSON/UML |

SimpleOntoDoc se centra en la simplicidad de descripción, cercana a los lenguajes de programación, evitando las complejidades de RDF/OWL.

Posibilidades de Mejora

• Interfaz multilingüe.
• Vista de árbol de clases con herencia.
• Analizadores para RDF/XML, OWL, XMI, PDF (GOST).
• Validación: min/max, regex para propiedades.
• Metadatos para clases/atributos.
• Anclas (#) para secciones de página.

Puntos Clave

• Genera un sitio completo con búsqueda, diagramas e hipervínculos.
• Entrada: JSON desde model.py, salida: archivos estáticos en Docker.
• Adaptado para CIM/GOST, extensible.
• Para desarrolladores de nivel medio/senior: enfoque en modelos de dominio sin complejidades de RDF.
• Integración CI para documentación en vivo.

— Editorial Team