Generator dokumentacji ontologii SimpleOntoDoc

Generator statycznej dokumentacji dla ontologii: implementacja i zastosowanie

SimpleOntoDoc — narzędzie do tworzenia statycznych stron z dokumentacją ontologii. Ontologia opisuje dziedzinę poprzez klasy, atrybuty i relacje między nimi. Projekt jest skierowany na wewnętrzne modele firm i standardy takie jak CIM (IEC61970), ale ma szersze zastosowanie.

Narzędzie generuje nawigację, diagramy, tabele właściwości i wyszukiwanie. Obsługuje parsowanie opisów schematów w formacie JSON, renderuje diagramy UML za pomocą PlantUML i wykorzystuje Bootstrap do interfejsu.

Struktura generowanej strony

Strona główna zawiera kafelki do szybkiego dostępu: Klasy, Enumeracje, Typy proste, Typy danych, Złożone. Każdy kafelek filtruje encje według typu. W nagłówku — wyszukiwanie bez uwzględniania wielkości liter po nazwach i opisach.

Zakładka Encje wyświetla tabelę wszystkich encji z interaktywnym wyszukiwaniem. Wiersze są klikalne, prowadzą do stron klas.

Na stronie klasy (przykład: PowerSystemResource):

• Opis i diagram UML hierarchii dziedziczenia + wychodzące relacje.
• Tabela właściwości z klikalnymi ID.
• Blok podsumowania: nawigacja po rodzicach, dzieciach, użyciu jako typ danych.
• Tabela odwołań: właściwości innych klas, gdzie dana klasa jest typem.
• Tabela klas potomnych.

Diagramy są interaktywne: panzoom do nawigacji, węzły są klikalne.

Strona właściwości (przykład: PowerSystemResource.Controls) zawiera opis, podsumowanie i nawigację.

Zastosowanie w projektach

Narzędzie nadaje się do domen z UML-podobnymi strukturami: klasy, dziedziczenie, kompozycja. Opisz ontologię w JSON (API model.py), wygeneruj stronę.

Warianty użycia:

• Dokumentacja encji biznesowych serwisu (50+ klas).
• Wspólny język między programistami, analitykami i autorami specyfikacji.
• CI/CD: generuj stronę przy zmianie JSON w Git.
• Podstawa do generowania kodu lub eksportu.

Oddziel ontologię od logiki biznesowej w specyfikacji.

Stos technologiczny

• C# / .NET 9: podstawa aplikacji.
• PlantUML: renderowanie diagramów UML przez tymczasowy serwer.
• RazorLight: szablonowanie stron.
• Bootstrap 5: układ frontendu.

Skrypt publikacji buduje kontener Docker z Nginx.

Porównanie z analogami

| Narzędzie | Zalety | Wady |

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

| ontology.tno.nl | Gotowe strony dla CIM | Brak kodu źródłowego, nie dostosowany do normy GOST |

| Widoco | Obsługa OWL | Jedna strona, zbędne informacje, design |

| Ontospy | Drzewo dziedziczenia | Wymaga modyfikacji pod JSON/UML |

SimpleOntoDoc skupia się na prostocie opisu, bliskiej językom programowania, unika złożoności RDF/OWL.

Możliwości rozbudowy

• Wielojęzyczność interfejsu.
• Widok drzewa klas z dziedziczeniem.
• Parsery dla RDF/XML, OWL, XMI, PDF (GOST).
• Walidacja: min/max, regex dla właściwości.
• Metadane dla klas/atrybutów.
• Kotwice (#) dla sekcji stron.

Co jest ważne

• Generuje pełnoprawną stronę z wyszukiwaniem, diagramami i hiperłączami.
• Wejście: JSON z model.py, wyjście: statyka w Docker.
• Dostosowane do CIM/GOST, rozszerzalne.
• Dla middle/senior: skupienie na modelach domenowych bez złożoności RDF.
• Integracja w CI dla dokumentacji na żywo.

— Editorial Team