Dokumentation liegt verteilt gespeichert vor und wird mit
dem mathcoach-resources-maven-plugin gebündelt. Dabei muss eine bestimmte
Verzeichnisstruktur eingehalten werden. Es wird zwischen Autoren-Dokumentation und
Entwickler-Dokumentation unterschieden. Weiterhin wird berücksichtigt, dass
Teile der Dokumentation (z.B. Indexdateien, Groovy-API-Doku, …) durch weitere
Mechanismen (z.B. Annotationen) dynamisch erzeugt wird. Teile der statischen
Dokumentation liegen im Artefakt mathcoach-docs bzw in den jeweiligen Artefakten. Die
Verzeichnis-Struktur des finalen Dokumentations-Quellcodes sieht etwa wie folgt aus:
mc-resources
└── mc-docs
├── author
│ ├── main.adoc // Einstiegspunkt
│ ├── generated // Zielort für generierte Dokumentation,...
│ │ └── groovy // ...jeweils in einem eigenen Verzeichnis
│ │ ├── ... // optional: weitere Dateien
│ │ └── main.adoc // Einstiegspunkt! (i.d.R. generiert)
│ └── ...
└── developer
├── main.adoc // Einstiegspunkt
├── modules // Zielort für Modul-Dokumentation
│ ├── [index.adoc] // wird generiert!
│ ├── module-a
│ │ └── main.adoc // Einstiegspunkt!
│ └── module-b
│ └── main.adoc // Einstiegspunkt!
└── ...
Da die verteilte Dokumentation aus vom mathcoach-resources-plugin "zusammenkopiert" wird,
kann statische und dynamische Dokumentation an verschiedenen Stellen erstellt werden.
Ein Artefakt, dass Dokumentation in den Resourcen anbietet, soll sich an
folgende Konventionen (alle Angaben relativ zu src/main/resources/mc-resources/)
halten, damit kein Durcheinander ensteht:
Diese Autoren-Dokumentation (allgemeine Worte zu den Aufgaben-Entwickler-Werkzeugen, …)
sollte im Artefakt mathcoach-docs unter mc-docs/author/ abgelegt werden und im
Einstiegspunkt mc-docs/author/main.adoc verlinkt werden.
Autoren-Dokumentation auf Modul-Ebene ist bisher nicht sinnvoll.
Teile der Autoren-Dokumentation (z.B. die Groovy-API Doku) lassen sich generieren. Diese
Doku soll vom Generierungs-Mechanismus (Maven-Plugin, …) nach
mc-docs/author/generated/<name>/ geschoben werden, wobei <name> ein eindeutiger
Name für die Teildokumentation sein soll (z.B. groovy für die Groovy-API Doku).
Der Einstiegspunkt muss jedoch händisch verlinkt werden (Artefakt mathcoach-docs, z.B.
in mc-docs/author/main.adoc ), da die Autoren-Dokumentation besonders lesbar sein soll und
diesen Freiheitsgrad benötigt.
Diese Autoren-Dokumentation (gesamte MathCoach-Architektur, usw.)
sollte im Artefakt mathcoach-docs unter mc-docs/developer/ abgelegt werden (und im
Einstiegspunkt mc-docs/developer/main.adoc verlinkt werden).
Jedes Modul (mc-database, mc-lti, …) hat die Möglichkeit eine
eigene Teil-Dokumentation zu verfassen. Diese soll im
jeweiligen Artefakt unter mc-docs/developer/modules/<name>/ abgelegt werden, wobei
<name> eindeutig gewählt werden soll und i.d.R. dem Namen des Artefaktes (z.B. mc-lti)
entspricht. Die Moduldokumentation wird automatisch indiziert. Dies setzt Vorraus, dass
der Einstiegspunkt mc-docs/developer/modules/<name>/main.adoc angelegt wird.
bisher noch nicht notwendig (später evtl. Übersicht über @NeedConfig-Angaben, usw.)