Générateur de documentation d'ontologie SimpleOntoDoc

Générateur de Documentation Statique pour Ontologies : Mise en Œuvre et Applications

SimpleOntoDoc est un outil pour créer des sites web statiques afin de documenter des ontologies. Une ontologie décrit un domaine sujet à travers des classes, des attributs et les relations entre eux. Le projet est orienté vers les modèles internes d'entreprise et les normes comme CIM (IEC61970), mais il a des applications plus larges.

L'outil génère une navigation, des diagrammes, des tableaux de propriétés et une fonctionnalité de recherche. Il prend en charge l'analyse des descriptions de schéma JSON, rend des diagrammes UML avec PlantUML et utilise Bootstrap pour l'interface.

Structure du Site Généré

La page d'accueil présente des tuiles pour un accès rapide : Classes, Énumérations, Primitifs, Types de Données, Composés. Chaque tuile filtre les entités par type. L'en-tête inclut une recherche insensible à la casse par noms et descriptions.

L'onglet Entités affiche un tableau de toutes les entités avec une recherche interactive. Les lignes sont cliquables et mènent aux pages de classe.

Sur une page de classe (exemple : PowerSystemResource) :

• Description et diagramme UML de la hiérarchie d'héritage + relations sortantes.
• Tableau des propriétés avec des ID cliquables.
• Bloc de résumé : navigation vers les parents, les enfants et l'utilisation comme type de données.
• Tableau de référence : propriétés d'autres classes où cette classe est le type.
• Tableau des classes enfants.

Les diagrammes sont interactifs : panzoom pour la navigation, les nœuds sont cliquables.

Une page de propriété (exemple : PowerSystemResource.Controls) inclut une description, un résumé et une navigation.

Applications dans les Projets

L'outil est adapté aux domaines avec des structures de type UML : classes, héritage, composition. Décrivez l'ontologie en JSON (API model.py), puis générez le site.

Cas d'utilisation :

• Documentation des entités métier dans un service (50+ classes).
• Langage commun entre développeurs, analystes et auteurs d'exigences.
• CI/CD : générez le site lorsque le JSON change dans Git.
• Fondation pour la génération de code ou l'exportation.

Séparez l'ontologie de la logique métier dans les exigences.

Pile Technologique

• C# / .NET 9 : fondation de l'application.
• PlantUML : rend les diagrammes UML via un serveur temporaire.
• RazorLight : modélisation des pages.
• Bootstrap 5 : mise en page frontend.

Le script de publication construit un conteneur Docker avec Nginx.

Comparaison avec les Alternatives

| Outil | Avantages | Inconvénients |

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

| ontology.tno.nl | Sites prêts à l'emploi pour CIM | Pas de code source, non adapté pour GOST |

| Widoco | Prise en charge OWL | Page unique, informations superflues, design |

| Ontospy | Arbre d'héritage | Nécessite des modifications pour JSON/UML |

SimpleOntoDoc se concentre sur la simplicité de description, proche des langages de programmation, évitant les complexités de RDF/OWL.

Possibilités d'Amélioration

• Interface multilingue.
• Vue arborescente des classes avec héritage.
• Analyseurs pour RDF/XML, OWL, XMI, PDF (GOST).
• Validation : min/max, regex pour les propriétés.
• Métadonnées pour les classes/attributs.
• Ancres (#) pour les sections de page.

Points Clés

• Génère un site complet avec recherche, diagrammes et hyperliens.
• Entrée : JSON de model.py, sortie : fichiers statiques dans Docker.
• Adapté pour CIM/GOST, extensible.
• Pour développeurs intermédiaires/seniors : concentrez-vous sur les modèles de domaine sans les complexités RDF.
• Intégration CI pour une documentation en direct.

— Editorial Team