w dniu
dev
devops
platform_engineering
security
- Pobierz link
- X
- Inne aplikacje
Asciidoctor to potężne narzędzie do generowania dokumentacji, które wykorzystuje prosty format tekstowy AsciiDoc. W połączeniu z Structurizr, narzędziem do modelowania architektury systemów, Asciidoctor umożliwia tworzenie kompletnej, łatwej w edycji i automatycznie aktualizowanej dokumentacji technicznej, która ewoluuje wraz z rozwojem projektu.
W tym przykładzie przedstawiam praktyczne zastosowanie integracji Asciidoctor ze Structurizr w konfiguracji Workspace DSL, gdzie pliki AsciiDoc są wbudowane w strukturę projektu.
Zakładamy, że w strukturze projektu znajduje się folder docs przeznaczony na dokumentację AsciiDoc oraz plik workspace.dsl do definiowania modeli w Structurizr.
/projekt
├── /docs
│ ├── index.adoc
│ └── architecture.adoc
├── workspace.dsl
└── ...inne pliki projektu
Przykładowy plik workspace.dsl
W pliku workspace.dsl definiujemy model architektury systemu. Przykład prostego modelu kontekstowego:
workspace {
model {
user = person "Użytkownik" {
description "Osoba korzystająca z systemu"
}
system = softwareSystem "System aplikacyjny" {
!docs docs
description "Aplikacja webowa"
user -> system "Używa"
}
}
views {
systemContext system {
include *
autolayout lr
}
theme default
}
}
W tym przykładzie:
Przykładowy plik index.adoc w folderze docs
W pliku index.adoc możemy umieścić opis systemu, informacje o jego architekturze oraz osadzić diagramy wygenerowane przez Structurizr:
= Dokumentacja architektury systemu
Autor: Zespół IT
:date: 2024-09-18
== Wprowadzenie
Ten dokument opisuje architekturę naszego systemu aplikacyjnego.
== Diagram kontekstowy
Poniżej znajduje się diagram kontekstowy, który pokazuje głównych uczestników systemu i ich interakcje:
image::system[]
Integracja Asciidoctor z Structurizr w ramach Workspace DSL to potężne narzędzie, które umożliwia zespołom IT efektywne tworzenie i zarządzanie dokumentacją techniczną. Dzięki tej integracji, zespoły mogą na bieżąco aktualizować dokumentację, zapewniając jej spójność z modelem architektury systemu, co znacznie ułatwia pracę i zwiększa efektywność projektu.
Komentarze
Prześlij komentarz