Erstellung von Dokumentation

Die wichtigste Dokumentation ist die Javadoc API-Dokumentation, die ihr auch rechts im Menü seht. Soweit es möglich ist, sollten alle Klassen und Methoden dort ausführlich dokumentiert werden, da so am ehesten gewährleistet ist, das man bei Änderungen am Quelltext auch die Doku mitändert.

Davon unabhängig gibt es ein Template-System, das die Webseite erstellt. In diese Seite kann man im Menü weitere Unterseiten einfügen und diese dann erstellen. Da ich dieses System gerne für verschiedene Projekte nutzen will (wir schreiben hier ein Framework, nicht wahr?), habe ich die Templates auf zwei Verzeichnisse verteilt: In doc/sitetemplate sind allgemeine Templates, die eine einfache, hübsche, aber nichtssagende Website ohne echten Content erstellen. In doc/site kann man dann einige dieser Dateien "überladen" bzw. auch noch beliebige neue hinzunehmen.

Dabei gibt es drei Formate, in denen Seiten geschrieben werden können:

• *.html: Diese Seiten werden unverändert in den Webauftritt kopiert. Dies erlaubt den genauesten Einfluss, macht es aber schwer, ein einheitliches Aussehen oder auch ein einheitliches Menü sicherzustellen.
• *.html.template: Diese Seiten werden durch einen Groovy-Templategenerator geschickt. Dieser versteht JSP-ähnliche Tags, die es erlauben, Property-Variablen aus dem Ant-Skript einzufügen, Teile bedingt oder in Schleifen auszuführen oder aber auch kompletten Groovy-Code auszuführen. Beispiele kann man sich in doc/sitetemplate ansehen.
• *.html.wiki: Diese Seiten werden zuerst durch eine einfache Wiki-Engine und dann ebenfalls durch obigen Template-Generator geschickt. Man kann hiermit einfach und schnell mit der einfachen Wiki-Syntax ordentliche Dokumente erstellen. Die Wiki-Syntax hat den Vorteil, daß man diese ggf. auch im Quelltext gut lesen kann. Man kann aber auch Wiki-Tags, JSP-Tags mit Variablen und Groovy-Code und HTML-Tags in einem einzigen Dokument wild mischen, wenn man das möchte.

Template-Engine

Die im Ant-Skript bzw. in dem von diesem eingelesenen Properties-Dateien stehenden Properties können einfach mit einem Dollar-Zeichen beuntzt werden. So heisst dieses Projekt laut der Variable $app_name "LugFramework". Wer mehr wissen will, kann in meine Beispiele schauen oder sich auf der Groovy-Seite umsehen. Auf dieser Seite habe ich die erweiterte Syntax für Includes abgeschaut.

Wiki-Engine

Die Wiki-Engine ist von mir in zwei Stunden mit Hilfe von ein paar regulären Ausdrücken geschrieben worden. Also erwartet nicht zu viel. RegExe sind zwar sehr mächtig, aber nach meiner Erfahrung keine exakte Wissenschaft. Man findet immer wieder einen Fall, der nicht richtig abgedeckt ist und muss daran herumfeilen. Wer Probleme findet, sollte mir also den entsprechenden Code als Beispiel schicken, dann kann ich nachbessern. Ein zweites Problem an der RegEx-Lösung ist, daß Sie in Java evtl. zu OutOfStackMemory-Problemen neigt. Wer sowas bekommt, sollte mir auch die entsprechende Datei schicken.

Bisher gehen Kursivdruck, Fettdruck, Überschriften, Links mit und ohne Bezeichnung, Absätze, Aufzählungen und Code-Abschnitte. Ein ganz gutes Beispiel für die Wiki-Syntax ist übrigens der Quellcode des Textes, den Ihr gerade lest.