Dokumentation

Dokumentation
2016-05-26
by Jens Kupferschmidt, Kathleen Neumann
Table of contents
1 Allgemeines.................................................................................................................. 2
2 An der Dokumentation mitarbeiten.............................................................................. 2
3 Inhalte erstellen.............................................................................................................2
3.1 Aufbau des Seiten-Header.......................................................................................2
3.2 Code-Beispiele mit Syntax-Highlighting................................................................ 2
3.3 Markieren von Funktionen, die bei folgenden Releases entfallen...........................3
Dokumentation
1 Allgemeines
Die Dokumentation von MyCoRe und die Unterstützung der Entwickler erfolgt über
mehrere Medien.
1.
2.
3.
Die MyCoRe-Dokumentation wird mit Apache Forrest erstellt. http://
www.mycore.de/documentation/index.html
Die Know-How- und Dokumentationsseiten der MyCoRe-Wiki-Installation http://
cmswiki.rrz.uni-hamburg.de/hummel/MyCoRe/Dokumentation dient als Platform für
ein Wissensforum zum Erfahrungsaustausch der Anwender.
Die Mailing-Listen für Benutzer und Entwickler zur direkten Kommunikation.
2 An der Dokumentation mitarbeiten
Für die Mitarbeit an der Dokumentation ist ein checkout von documentation vom SVNTrunk erforderlich. Um die Dokumentation lokal zu aktivieren, ist die Installation von
Apache Forrest v0.9 erforderlich. Es muss die Environment-Variable FORREST_HOME
gesetzt werden. Für den Start ist in das root-Verzeichnis der Dokumentation zu wechseln.
Vor der ersten Nutzung muss das Kommando ant config-fop aufgerufen werden. Danach
kann mit forrest run eine lokale Dokumentation gebaut und über http://localhost:8888
im Browser aufgerufen werden. Änderungen sind dabei immer sofort sichtbar, es ist kein
erneuter Aufruf nötig.
Die Sprache der Dokumente ist wahlweise Deutsch oder Englisch.
3 Inhalte erstellen
3.1 Aufbau des Seiten-Header
Um auf der Webseite Seitenautor und letzte Änderung ausgeben zu lassen, sind
die header-tags <authors und <version> zu verwenden. Die Angabe der
Personennamen erfolgt in der Form "Vorname Nachname", die Version enthält das
Datum der aktuellen Änderung in ISO-Form: YYYY-MM-DD. Weiterhin ist anzugeben,
für welcher Releases diese Seite Gültigkeit hat. Dabei können auch, wie im Beispiel,
mehrere Release-Stände angegeben werden, wenn dies zutrifft.
<header> <title>Meine Testseite</title> <release>2015.05</release> <release>2016.06</
release> <version>2016-11-11</version> <authors> <person email="[EMAIL
PROTECTED]" name="Max Mustermann" /> </authors> </header>
3.2 Code-Beispiele mit Syntax-Highlighting
Für eine gut lesbare Darstellung der Code-Beispiele nutzen wir den SyntaxHighlighter,
eine JavaScript-Entwicklung. Dazu muss ein <pre>-Tag mit der CSS-Klasse brush:
[language]; definiert werden:
Seite 2 von 3
Dokumentation
<pre class="brush: xml;"><![CDATA[ <example>Dies ist ein XML-Codebeispiel</
example> </pre>
Standardmäßig stehen die Layouts brush: xml, brush: bash und brush:
java zur Verfügung. Sollten weitere Layouts benötigt werden, können diese wie folgt
eingebunden werden, z.B. brush: sql,:
<!-- You need to include a brush for every language you want to highlight --> <script
type="text/javascript" src="/documentation/skin/shBrushSql.js"></script> <pre
class="brush: sql; gutter: false;"> SELECT * FROM mcrcategory; </pre>
3.3 Markieren von Funktionen, die bei folgenden Releases entfallen
Um zu markieren, dass die beschriebene Funktion beim nächsten Release entfällt, ist
folgender Codeabschnitt vorgesehen.
<span class="label label-danger">deprecate</span>
Seite 3 von 3