Generátor dokumentace ontologií SimpleOntoDoc

Generátor statické dokumentace pro ontologie: implementace a využití

SimpleOntoDoc je nástroj pro vytváření statických webů s dokumentací ontologií. Ontologie popisuje doménu prostřednictvím tříd, atributů a vztahů mezi nimi. Projekt je zaměřen na interní modely společností a standardy jako CIM (IEC61970), ale je použitelný i v širším kontextu.

Nástroj generuje navigaci, diagramy, tabulky vlastností a vyhledávání. Podporuje parsování JSON popisů schémat, vykresluje UML diagramy pomocí PlantUML a používá Bootstrap pro uživatelské rozhraní.

Struktura generovaného webu

Hlavní stránka obsahuje dlaždice pro rychlý přístup: Třídy, Výčty, Primitiva, Datové typy, Složené typy. Každá dlaždice filtruje entity podle typu. V záhlaví je nezávislé na velikosti písmen vyhledávání podle názvů a popisů.

Záložka Entity zobrazuje tabulku všech entit s interaktivním vyhledáváním. Řádky jsou klikatelné a vedou na stránky tříd.

Na stránce třídy (příklad: PowerSystemResource):

• Popis a UML diagram hierarchie dědičnosti + odchozí vazby.
• Tabulka vlastností s klikatelnými ID.
• Blok shrnutí: navigace po rodičích, dětech, použití jako datový typ.
• Tabulka odkazů: vlastnosti jiných tříd, kde je daná třída typem.
• Tabulka podřízených tříd.

Diagramy jsou interaktivní: panzoom pro navigaci, uzly jsou klikatelné.

Stránka vlastnosti (příklad: PowerSystemResource.Controls) zahrnuje popis, shrnutí a navigaci.

Využití v projektech

Nástroj je vhodný pro domény s UML-podobnými strukturami: třídy, dědičnost, kompozice. Popište ontologii v JSON (model.py API), vygenerujte web.

Možnosti využití:

• Dokumentace obchodních entit služby (50+ tříd).
• Společný jazyk mezi vývojáři, analytiky a autory specifikací.
• CI/CD: generujte web při změně JSON v Gitu.
• Základ pro generování kódu nebo export.

Oddělte ontologii od obchodní logiky ve specifikacích.

Technologický stack

• C# / .NET 9: základ aplikace.
• PlantUML: vykreslování UML diagramů přes dočasný server.
• RazorLight: šablonování stránek.
• Bootstrap 5: frontend layout.

Skript publikace vytváří Docker kontejner s Nginx.

Srovnání s analogy

| Nástroj | Výhody | Nevýhody |

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

| ontology.tno.nl | Hotové weby pro CIM | Žádný zdrojový kód, neadaptovaný pro české normy |

| Widoco | Podpora OWL | Jedna stránka, nadbytečné informace, design |

| Ontospy | Strom dědičnosti | Vyžaduje úpravy pro JSON/UML |

SimpleOntoDoc se zaměřuje na jednoduchost popisu, blízkou programovacím jazykům, vyhýbá se složitostem RDF/OWL.

Možnosti vylepšení

• Vícejazyčnost rozhraní.
• Stromový pohled tříd s dědičností.
• Parsery pro RDF/XML, OWL, XMI, PDF (české normy).
• Validace: min/max, regex pro vlastnosti.
• Metadata pro třídy/atributy.
• Kotvy (#) pro sekce stránek.

Co je důležité

• Generuje plnohodnotný web s vyhledáváním, diagramy a hypertextovými odkazy.
• Vstup: JSON z model.py, výstup: statika v Dockeru.
• Adaptováno pro CIM/české normy, rozšiřitelné.
• Pro middle/senior: zaměření na doménové modely bez RDF složitostí.
• Integrace do CI pro živou dokumentaci.

— Editorial Team