Format dokumentacji

Dokumentacja techniczna i użytkownika są tworzone przy użyciu Maven 2 Site Plugin . Źródła dokumentacji znajdują się w katalogu src/site repozytorium SVN aplikacji, w pluginie CAST Core.

Organizacja źródeł

  • pom.xml - plik konfiguracji Maven opisujący stronę
  • src\site - źródła strony
    • apt - główny katalog z dokumentacją w formacie APT; opis formatu APT na stronach projektu Doxia
    • confluence - główny katalog z dokumentacją w formacie Confluence; opis formatu Confluence na stronach projektu. Uwaga, obsługiwany jest jedynie mały podzbiór formatu Confluence
    • resources - katalog z obrazkami, schematami itp. zasobami
    • site.xml - plik XML opisujący stronę, w szczególności menu z lewej strony
    • no-menu.vm - szablon strony nie posiadający menu, przeznaczony do generowania helpu Eclipse
  • target\site - katalog wyjściowy, gdzie generowana jest strona
  • target\eclipse-help - katalog wyjściowy, gdzie generowany jest help Eclipse (patrz niżej)

Konwencje

W dokumentacji nie należy używać jawnie nazwy projektu (CAST/LINK) . Zamiast tego należy używać tekstu ${shortAppName} , który w trakcie generowania strony jest zastępowany przez odpowiednią nazwę zależnie od tego w jakim celu jest generowana dokumentacja (strona WWW dla CASTa, help Eclipse dla LINKa).

Pliki dokumentacji muszą być zakodowane w formacie UTF-8 .

Aktualizacja dokumentacji

Aby wygenerować dokumentację, należy wykonać polecenie mvn clean site . Dokumentacja jest generowana w katalogu target/site .

Aby wygenerować help w formacie Eclipse, należy wykonać polecenie mvn clean site -P eclipse-help . Help jest generowany w katalogu target/eclipse-help .

Przydatne jest używanie także parametru -e do polecenia mvn , które wyświetla szczegóły wyjątków występujących w czasie generowania strony. Pozwala to na prostszą lokalizację błędów.

Deployowanie dokumentacji

Użycie targetu site-deploy zamiast site powoduje, że strona po wygenerowaniu jest od razu wrzucana na serwer. Opis tego mechanizmu jest dostępny w dokumentacji Maven Site, w sekcji Deploying the Site .

Nie należy używać site-deploy w przypadku helpu Eclipse!