Skip to content
Endbenutzer-Dokumentation der Software-Challenge Germany
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
allgemein
bin
entwicklung
images
software
source-images
spiele
.gitignore
Guardfile
README.adoc
docs
getting-started.adoc
index.adoc

README.adoc

Software Challenge Endbenutzer-Dokumentation-Dokumentation

In diesem Repository befindet sich die Endbenutzer-Dokumentation fuer die Software Challenge. Zielgruppe sind Schüler und Lehrer, die an der Software Challenge teilnehmen.

Beitragen

Wir freuen uns über sämtliche Verbesserungsvorschläge. Die Dokumentation kann direkt hier auf GitHub editiert werden, einzige Voraussetzung ist eine kostenlose Registrierung bei GitHub. Ist man angemeldet, kann man ein Dokument auswählen (ein guter Startpunkt ist die Datei index.adoc welche Verweise auf alle Sektionen der Dokumentation enthält) und dann auf den Stift oben rechts klicken. Alternativ auch gern eine E-Mail an svk@informatik.uni-kiel.de.

Konventionen

  • Die Hauptdatei ist index.adoc im Wurzelverzeichnis. Alle anderen Dateien werden per include-Anweisung in die Hauptdatei eingebunden.

  • Dateinamen und Verzeichnisnahmen sollten nur die Zeichen a bis z sowie Bindestriche (-) enthalten.

  • Sprache fuer Dateinamen, Verzeichnisnamen sowie Inhalt ist Deutsch. Sprache fuer Attribute und sonstige Interna ist Englisch.

  • Als Endung fuer Asciidoc wird .adoc benutzt.

  • Es wird des ATX-Format fuer Ueberschriften verwendet (also =, ==, === etc.)

  • Keine Umbrüche innerhalb von Paragraphen. Für eine lesbare Darstellung der Quellen sollte ein Editor mit aktiviertem Soft-Wrap verendet werden.

Konvertierung

Um schnell starten zu können, existiert ein setup, das folgendermaßen aufgerufen werden kann.

./docs setup

Dies installiert die beiden Ruby-Gems asciidoctor und pygments.rb (für Syntax-Highlighting der Quellcodes), außerdem das Gem asciidoctor-pdf, welches aber im Moment nur im "Prerelease"-Status ist, es wird also per gem install --prerelease asciidoctor-pdf installiert.
Schließlich installiert es auch den post-commit-hook, sodass pushes zu master automatisch auf der Website landen.

Um alles in HTML zu Übersetzen, sollte folgender Befehl verwendet werden:

./docs generate

Wenn zusätzlich die Option pdf angehängt wird, wird auch asciidoctor-pdf aufgerufen. Aus Geschwindigkeitsgründen wird darauf standardmäßig verzichtet.

Intern wird asciidoctor verwendet:

asciidoctor -D out index.adoc

Die fertige HTML-Version befindet sich dann unter out/index.html.

Bei Bedarf kann die Dokumentation auch in ein anderes Format konvertiert werden, Details hierzu finden sich in der AsciiDoctor Dokumentation.

Live-Preview

Noch nicht vollständig getestet. Im Moment sehr langsam, da alles neu übersetzt wird.

Einen Live-Preview-Mode gibt es leider nicht direkt, aber es gibt verschiedene Wege um ein Live-Preview zu bekommen. Einer ist die Nutzung von guard. Dies kann durch folgenden Aufruf installiert werden:

./docs setup live

Dies installiert dann die folgenden Gems: guard guard-shell guard-livereload yajl-ruby

Ein passendes Guardfile liegt schon im Repository, man kann guard also einfach mittels guard start starten, und die Ausgabe im Verzeichnis out wird aktualisiert, sobald man etwas an den Quellen ändert.

Wenn man dann noch die Browseransicht automatisch aktualisieren lassen will, muss man eine LiveReload Extension für Firefox oder Chrome installieren.

Deployment

Um die Dokumentation unter https://cau-kiel-tech-inf.github.io/socha-enduser-docs/ automatisch aktualisieren zu lassen, sind Schreibrechte für dieses GitHub Repository erforderlich.

Wenn ./docs setup verwendet wurde, kann direkt statt eines commits im master-branch ./docs publish verwendet werden. Es stellt sicher, dass das Deployment korrekt vonstatten geht.

Ansonsten muss zuerst der post-commit-hook installiert werden. Dazu einfach die Datei git-post-commit-hook.sh aus dem Verzeichnis bin zu .git/hooks/post-commit kopieren.

Dann wird nach jedem commit auf master alles automatisch konvertiert und online gestellt (inklusive der Bilder).

Quickstart

Es werden häufig Links zu anderen Teilen des Dokumentes genutzt (die Dokumentation ist ein einzelnes großes Dokument). Diese haben die Syntax:

<<Sektionslabel,anzuzeigender Linktext>>

Wobei Sektionslabel über allen Überschriften stehen und die Syntax ist wie folgt:

[[labelname]]
You can’t perform that action at this time.