In diesem Repository befindet sich die Endbenutzer-Dokumentation für die Software-Challenge. Zielgruppe sind Schülerinnen, Schüler und Lehrkräfte, die an der Software-Challenge teilnehmen.
Ziel dieser Dokumentation ist es, alle Informationen über die Software-Challenge an einer Stelle zu bündeln. Hier können sich Lehrkräfte und Kursleiter über den Zweck der Software-Challenge informieren. Für die teilnehmenden Teams ist hier alles dokumentiert, was für die Teilnahme am Wettbewerb benötigt wird.
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.
Nach der Anmeldung ein Dokument auswählen
und dann auf den Stift oben rechts klicken.
Die relevanten Dokumente finden sich im Verzeichnis hyperbook/book.
Damit wird von GitHub automatisch ein Fork
und ein dazugehöriges Pull Request erstellt.
Alternativ auch gerne per E-Mail an tech@software-challenge.de
oder als Nachricht im Discord.
- Zeilenumbrüche jeweils am Ende von Sätzen bzw. semantischen Grenzen, orientiert an Semantic Line Breaks.
- Datei- und Verzeichnisnamen sollten nur die Zeichen
abiszsowie Bindestriche (-) enthalten. - Sprache für Dateinamen, Verzeichnisnamen sowie Inhalt ist Deutsch. Sprache für Attribute und sonstige Interna ist Englisch.
Commitnachrichten wird der Dateipfad der geänderten Datei oder des Ordners vorangestellt, ggf. gekürzt um überflüssige Elemente (z.B. 'blokus/' statt 'spiele/blokus/'). Um bei den Branches die Übersicht zu behalten, sollten diese ebenfalls nach der Konvention benannt werden. Darüber hinaus guten Stil beachten: https://cbea.ms/git-commit/
Ansonsten folgend wir soweit sinnvoll der Kull Konvention.
Die Dokumentation wird mit der Software Hyperbook bereitgestellt.
Die einzelnen Seiten sind im Ordner hyperbook im Markdown-Syntax hinterlegt
und können mit einem entsprechenden Editor bearbeitet werden.
Im hyperbook-Ordner sollte auch jeder folgende Befehl ausgeführt werden.
Um Hyperbook zu HTML zu konvertieren,
muss die Laufzeitumgebung Node.js installiert sein.
Dies geht unter Debian-basierten Distributionen mit sudo apt install nodejs npm.
Unter Arch: sudo pacman -S npm
Anschließend installiere die Abhängigkeiten mit
npx hyperbook setup oder make -B setup.
Eine Vorschau lokaler Änderungen kann direkt mit dem Befehl npx hyperbook dev
aus dem Ordner hyperbook generiert werden.
Dies startet einen Entwicklungsserver,
dessen Ergebnisse unter http://localhost:3000/ einsehbar sind.
Um das Hyperbook zu veröffentlichen,
generiert npx hyperbook build die Website in ./hyperbook/.hyperbook/out.
Die öffentliche Seite
wird automatisch bei jedem push in den main-Branch von GitHub aktualisiert.
Dies geschieht durch einen GitHub Actions Workflow,
siehe .github/workflows/auto-publish.yml.
Der Workflow speichert die generierten Seiten im live branch des Repositories,
welcher nach Benachrichtigung durch einen Webhook von caddy gepullt wird.
Bei Änderungen am Caddyfile oder dem Docker image muss push-production.sh mit dem GITHUB_SECRET des Webhooks ausgeführt werden. Der Docker container lässt sich auch lokal mit test-production.sh testen, wobei der Caddy Webserver auf port 80 via localhost erreichbar wird.
TODO: Eigenes Caddyfile mit "debug" und Dockerfile mit lokalem build für testing