HowTo: Dokumentieren auf Bloonix.org

Github Repository

Die gesamte Dokumentation von Bloonix befindet sich auf Github im Repository Github: bloonix.org .

Pfade

Pfad	Beschreibung
public/css	CSS-Dateien. Standardmäßig wird die Datei webapp.css geladen.
public/img	Bilder wie PNG, JPEG.
public/js	Javascript Dateien. Standardmäßig wird die Datei webapp.js geladen.
templates	Hier liegen die Dokumente in Unterordnern.

Unterhalb des Verzeichnisses templates wird zunächst ein Verzeichnis im Format eines Länderkürzels angelegt, welches der Sprache entspricht, in welches die Dokumenten geschrieben sind.

Beispiel:

templates/de/docs # Deutsch
templates/en/docs # Englisch

Ab dem Verzeichnis docs gibt es in jedem Verzeichnis und den Unterverzeichnissen eine Datei namens order.json. Diese Datei ist wichtig für das Inhaltsverzeichnis der Dokumentation und die Reihenfolge der Dokumente.

cat templates/de/docs/order.json
[
    { "Über Bloonix": "about.textile" },
    { "Lizenzen": "license.textile" },
    { "Komponenten": "components" },
    { "Installation": "installation" },
    { "Konfiguration": "configuration" },
    { "HowTos": "howtos" }
]

Der Aufbau der Datei ist recht einfach. Dokumente erhalten immer .textile als Endung.

[
    { "Titel des Dokuments" : "datei.textile" },
    { "Titel des Verzeichnisses" : "verzeichnis" }
]

Textile Markup

Die Dokumentation von Bloonix ist in Textile geschrieben. Aus diesem Grund erhalten alle Dokumente die Dateiendung .textile.

Bei der Gestaltung der Dokumente gibt es ein paar Regeln, die beachtet werden sollten, damit alle Dokumente lesbar und einheitlich sind.

h2-Titel sollten keine Sonderzeichen enthalten, ausser Leerzeichen und die folgenden Zeichen .,;:
Versuche, das Dokument und den Inhalt auf die vordefinierten CSS-Klassen der Dokumentation anzupassen.
Die Breite für den Inhalt beträgt derzeit 900 Pixel. Bilder sollten nicht größer sein oder skaliert werden.
Versuche, so wenig bis garkeine eigenen Styles zu verwenden.

Anker und Links

h2-Tags

Aus den h2-Tags wird das Inhaltsverzeichnis eines Dokuments mittels Javascript automatisch generiert. Dieses erscheint dann oben rechts. Der Text aus den h2-Tags wird als Anker verwendet und sollte daher nur aus bestimmten Zeichen bestehen. Ausser den normalen Zahlen und Buchstaben sollten nur folgende Sonderzeichen verwendet werden: Leerzeichen und +-_.,;:

a-Tags

Bei allen a-Tags wird automatisch bei der Generierung des Dokuments das Attribut target="_blank" hinzugefügt. Es ist also nicht notwendig, dies selbst zu machen.