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!