W poprzednim artykule Generowanie raportu ze zmianami w modelu …. opisałem prace związane z przygotowaniem Tormigo do generowania dokumentacji prezentującej zmiany w modelu Enterprise Architect. W tej części opiszę sposób generowania dokumentacji.
Generowanie dokumentacji
Generowanie dokumentacji dla projektu uruchamia się przez kliknięcie przycisku „Generuj dokumentację” w oknie konfiguracji projektu. Kliknięcie tego przycisku spowoduje wyświetlenie okna generatora dokumentacji. Zawartość wygenerowanego dokumentu MS Word będzie różna w zależności od konfiguracji szablonu oraz rodzaju generowanej dokumentacji. Użytkownik ma możliwość określenia jakie typy elementów będą uwzględnione w dokumentacji.
Opis generatora dokumentacji
Okno generatora dokumentacji pozwala na określenie parametrów dokumentacji oraz wygenerowanie dokumentacji zmiany lub dokumentacji dla wybranych pakietów. W przypadku generowania dokumentacji zmiany aplikacja w ramach dokumentacji zamieści:
- · wszystkie pakiety, które w nazwie posiadają kod zmiany,
- · wszystkie pakiety, które posiadają przypisany element Maintenace Change, który w nazwie posiada kod zmiany,
- · wszystkie elementy, które posiadają przypisany element Maintenace Change, który w nazwie posiada kod zmiany,
- · wszystkie diagramy, które w polu Notes posiadają kod zmiany.
Kod zmiany możliwy jest do określenia po uruchomieniu generacji dokumentacji. Domyślnie kod zmiany odpowiada kodowi projektu.
W przypadku generowania dokumentacji dla wybranych pakietów, dla każdego repozytorium użytkownik może wybrać pakiety, które zostaną uwzględnione w dokumentacji.
Poniżej został przedstawiony przykładowy widok z generatora dokumentacji.
Okno generatora dokumentacji podzielone jest na zakładki umożliwiające określenie parametrów szablonu dokumentacji, zawartości dokumentacji oraz przycisków służących do generowania dokumentacji.
- Zakładka: Właściwości
- Zakładka pozwala na określenie szablonu dokumentacji oraz jego podstawowych parametrów.
- Pole Plik szablonu – pozwala na określenie ścieżki do pliku z szablonem dokumentacji.
- Pole Numer pierwszego rozdziału – pozwala na określenie wartości pierwszego wygenerowanego rozdziału dokumentacji. Ustawienie wartości na 0 powoduję pominięcie nadawania rozdziałom numerów.
- Pole Maksymalny numer nagłówka do użycia w nazwie rozdziału – pozwala na określenie najwyższego numeru stylu, który będzie zastosowany w nazwach kolejnych podrozdziałów.
- Panel Szablon – pozwala na otworzenie, zapisanie i usunięcie ustawień szablonu dokumentacji.
- Zakładka: Style
Zakładka pozwala zdefiniować nazwy stylów w szablonie. Dla języka obsługiwanego przez Tormigo zostaną wygenerowane domyślne nazwy stylów. Przy każdym definiowaniu szablonu, należy sprawdzić czy szablon zawiera tak zdefiniowane nazwy stylów. W procesie generowania dokumentu próba użycia stylu niezdefiniowanego w szablonie przerwie proces generowania dokumentu z odpowiednim komunikatem. Dodatkowo w zakładce możliwe jest zdefiniowanie dwóch parametrów:
- · Użyj stylów nagłówka dla nazw elementów – definiuje czy dla nazw elementów mają być stosowane style nagłówka (z zachowaniem hierarchii podrozdziałów). Pozostawienie tego pola pustego spowoduje, że dla nazwy elementu zostanie użyty styl Element.
- · Dodawaj numery rysunków – określa czy generator ma numerować diagramy dodawane do dokumentacji.
Zakładka: Typy elementów do uwzględnienia
Zakładka pozwala na zaznaczenie typów elementów, jakie mają zostać uwzględnione w dokumentacji. Aby typ elementu został uwzględniony musi być zaznaczone pole wyboru przy nazwie typu. Przycisk Zaznacz wszystko spowoduje zaznaczenie wszystkich typów elementów, a przycisk Odznacz wszystko – odpowiednio odznaczenie wszystkich typów elementów.
Zakładka: Zawartość
Zakładka pozwala na określenie, które właściwości elementów i pakietów zostaną wyświetlone w dokumentacji. W zakładce znajdują się trzy panele:
- · Właściwości elementów – określa, które właściwości elementów zostaną wyświetlone w dokumentacji,
- · Właściwości pakietów – określa, które właściwości pakietów zostaną wyświetlone w dokumentacji,
- · Opcje – określa jakie elementy powiązane z pakietami i innymi elementami zostaną wyświetlone w dokumentacji.
Plik szablonu
Dokumentacja generowana jest na podstawie pliku szablonu. Plikiem szablonu jest wstępnie sformatowany dokument MS Word. Dokument musi zawierać klauzulę {doc.Content}, która będzie zamieniona przez wygenerowaną treść. W ramach szablonu można skorzystać z pól zawierających następujące właściwości dokumentu: Title, Author, Company, Keywords, Category, Subject, Comments. Podczas generowania dokumentów pola te zostaną uzupełnione wartościami zdefiniowanymi dla projektu. Użyj w programie MS Word opcji Wstawianie | Tekst | Szybkie części | Właściwości dokumentu | Autor, aby wstawić pole z autorami projektu. Poniżej został zamieszczony przykładowy wycinek szablonu.
Generowanie dokumentacji zmiany
Dokumentacja zmiany zawiera:
- · wszystkie pakiety, które w nazwie posiadają kod zmiany,
- · wszystkie pakiety, które posiadają przypisany element Maintenace Change, który w nazwie posiada kod zmiany,
- · wszystkie elementy, które posiadają przypisany element Maintenace Change, który w nazwie posiada kod zmiany,
- · wszystkie diagramy, które w polu Notes posiadają kod zmiany.
Do każdego pakietu i elementu spełniającego te kryteria zostaną także dołączone wszystkie zawarte w nim pakiety i elementy, które będą spełniały filtry określone w generatorze szablonu, jak np. elementy Maintenance.
Generator dokumentacji zmiany przeszukuje po kolei repozytoria przypisane do projektu. W pierwszym kroku poszukuje w repozytorium pakietów, które w nazwie posiadają zawarty kod zmiany (kod projektu). Na przykład jeżeli generator (dla kodu zmiany „PR-DK-01”) znajdzie pakiet o nazwie „Opis projektu PR-DK-01” to dołączy go do generowanego dokumentu oraz wszystkie elementy z jego struktury, które zostały zaznaczone w oknie generatora dokumentacji. W kolejnych krokach system wyszuka pakiety, a później elementy modelu, które mają przypisaną zmianę (Maintenace Change) o nazwie zawierającej kod zmiany. Ostanim krokiem generowania dokumentacji zmiany dla danego repozytorium jest wyszukanie wszytskich diagramów, które w polu Notes także zawierają kod zmiany.
Aby przypisać zmianę Maintenace Change w Enterprise Architect zaznacz w drzewie projektu element, do którego zmiana ma być przypisana. Następnie w oknie Maintenance (ALT + 4) wybierz zakładkę Changes i kliknij ikonę New. W formularzu opsiu zmiany w polu Name umieść kod zmiany (projektu). Nazwę zmiany możesz uzupełnić o krótką informację, czego zmiana dotyczy. Uzupełnij pozostałe pola formularza. Po uzupełnieniu kliknij ikonę Save, aby zapisać zmiany. Poniżej został zamieszczony przykładowy formularz opisujący zmianę wymagania.
Rozpoczęcie generowania dokumentacji zmiany wywoływane jest przyciskiem „Generuj dokumentację zmiany” w oknie generatora dokumentacji. Aplikacja wyświetli okno dialogowe z prośbą o wprowadzenie kodu zmiany w projekcie. Domyślną wartością kodu zmiany jest kod projektu.
Po naciśnięciu przycisku OK zostanie uruchomiona operacja generowania dokumentacji. Poniżej został przedstawiony fragment wygenerowanej dokumentacji, zawierający wycinek z dokumentacji:
- · pakietu zawierającego w nazwie kod zmiany,
- · wymagania do którego została przypisana zmiana Maintenance Change z nazwą zawierającą kod zmiany.
Generowanie dokumentacji wybranych pakietów
Generowanie dokumentacji dla wybranych pakietów odbywa się przez kliknięcie przycisku „Generuj dokumentację pakietów” w oknie generatora dokumentacji. Po uruchomieniu generatora użytkownik ma możliwość wskazania pakietów, które zostaną uwzględnione w dokumentacji.
Zaznaczenie opcji „Wstaw repozytorium jako nową sekcję w dokumencie” spowoduje dodanie oddzielnego podrozdziału dla każdego repozytorium.
Kliknięcie przycisku OK spowoduje rozpoczęcie generowania dokumentacji. W wygenerowanym dokumencie zostaną zawarte wszystkie zaznaczone pakiety wraz z zamieszczonymi w nich elementami i diagramami. Poniżej został zamieszczony wycinek dokumentacji dla wybranych pakietów.
Tak wygenerowana dokumentacja może trafić do dalszej obróbki - analizy przez wybranych interesariuszy. W trakcie takiej analizy uwagi zapisywane są zazwyczaj jako komentarze do tekstu w MS Word. Tormigo pozwala na ich automatyczne wczytanie. Opisałem to tutaj: Jak szybko przenieść komentarze z MS Word do Enterprise Architect?