README.rst

Git der MATERIALSAMMLUNG

Die Materialsammlung geht auf die Arbeit von verschiedenen Referendarinnen und Referendaren der Informatikfachseminare Hamm und Arnsberg zurück. Diese wurden geordnet, überarbeitet und ergänzt auf der Seite https://ddi.uni-wuppertal.de/www-madin//material/materialsammlung/index.html veröffentlicht.

Um die Arbeit für die Sammlung zu erleichtern, wurde begonnen, diese auf ein neue Grundlage gestellt. Dabei sollten unter anderem die Materialien selber die Daten bekommen, die später auf der Internetseite über das Dokument und die damit verbundenen Elemente dargestellt würden. Die neu hinzugefügten Module richten sich direkt an Lehrkräfte. In ihnen wird die Einbindung der Informations- und Arbeitsblätter beschrieben. Dabei kann es sich um eine eine komplette Unterrichtsreihe, als auch um eine kurze Sequenz handeln.

Mit der Veröffentlichung des Git der Materialsammlung wird zum einen die neusten Entwicklungen auch wieder der Öffentlichkeit zugänglich gemacht. Zum anderen können sich nun auch alle Interessierten einfacher daran beteiligen. Dieses könnte durch das Querlesen und Bereinigen von Fehlern geschehen, als auch durch das Hinzufügen von neuen Elementen oder Alternativen zu bereits bestehenden. Dabei muss nur beachtet werden, dass die Materialien im Sinne von "Open Educational Resources" frei und offen sind.

Die Veröffentlichung der Materialsammlung auf einer eigenen Webseite wird weiterhin angestrebt. Die Erweiterung der Sammlung steht aber im Vordergrund.

Anforderungen

Um die Elemente der Material lokal ausspielen und sie neu setzen zu können wird folgendes benötigt:

• git
• git-lfs
• LaTeX mit
  • gitfile-info.sty -> Verfügbar bei ctan, Scripte unter bin/
  • ddipub.cls und ddipub.sty -> Verfügbar unter texmf/
• python >3 (ggfs. pip[3] oder easy_install) mit
  • gitpython -> verfügbar per pip

Für das automatische Erstellen einer Webseite wird zusätzlich folgendes benötigt:

• python >3 (ggfs. pip[3] oder easy_install) mit
  • latex2markdown -> verfügbar per pip
  • markdown -> verfügbar per pip
  • PyPDF2 -> verfügbar per pip
  • wand -> verfügbar per pip
  • pelican -> verfügbar per pip
  • configparser -> verfügbar per pip
• Optional: ebook-convert (für Erstellung der Dokumentation im mobi Format)

Initialisierung Git

Bei der Materialsammlung wird LFS genutzt, um größere Dateien nicht direkt im Git zu speichern. Dazu gehören alle PDF-Dateien, die sich aus den LaTeX-Dateien erzeugen lassen. Außerdem wird gitfile-info ein Mechanismus genutzt, um das Datum des letzten Commits einer Datei im kompilierten PDF mit anzuzeigen. Beides muss bei der Einrichtung beachtet werden.

Erstes Klonen des Repositories

Vor dem ersten Klonen sollte git-lfs installiert und die Initialisierung für das komplette System mit

git lfs install

ausgeführt werden. Nach dem ersten Klonen ist es notwendig die Datei bin/config auszuführen.

Diese Schritte wurden in einem Linux-System ausgeführt. Je nach System könnten aber Anpassungen notwendig sein, die auch in diese Anleitung übernommen werden können.

Einrichtung der Webseitenerstellung

Die folgenden Schritte sind nur nach dem ersten Klon notwendig, um das Repository so nutzen zu können, um damit auch die Webseite erstellen zu können.

• Um die Installation notwendiger Python-Module durchzuführen, kann bin/install (als root) ausgeführt werden.
• Kopiere die Datei bin/ddipubWeb.cfg.default nach bin/ddipubWeb.cfg. Entwickler, die Webseiten hochladen dürfen, tragen den passenden <account> unter [Web] für www-madin ein.
• Führe bin/ddipubWeb.py init aus, um die benötigten Verzeichnisse zu erstellen.

Die Initialisierung von gitfile-info kann auch durch das Script bin/config erledigt werden. Je nach System könnten aber Anpassungen notwendig sein.

Initialisierung von LaTeX

Um Modulhandbücher und Materialien setzen zu können, müssen die Dateien aus dem Verzeichnis texmf für LaTeX lesbar platziert werden, z.B. indem weiche Verweise der Elemente von ~/texmf/tex/latex/ aus zu den Elementen in path/to/matsam/texmf/ erstellt werden.

Dokumentation/Hinweise

Im Verzeichnis doc/ befindet sich eine automatisierte SPHINX-Dokumentation, die u.a. die Docstrings der python-Scripte auswertet. Diese kann wie folgt erzeugt werden:

• make html (unter _build/html/ befindet sich nun eine Dokumentationswebseite)
• make latexpdf (unter _build/latex/ wurde nun eine PDF-Datei mit der gesamten Doku erzeugt -- LaTeX muss hierfür vorhanden sein)
• make epub3 (unter _build/epub3/ wurde nun eine epub-Datei mit der gesamten Doku platziert)
• make mobi (unter _build/mobi/ wurde nun eine mobi-Datei mit der gesamten Doku platziert -- hierfür muss ebook-convert installiert sein)
• make all (nacheinander wird zunächst html, latexpdf, epub3 und mobi ausgeführt)

Developers-Guide

Branches

Die Materialsammlung arbeitet zur einfacheren Verwaltung mit hierarchisch angeordneten branches.

• master: enthält den aktuellen, veröffentlichten, stabilen Stand (Webseite)
• stable: enthält getestete und validen Stand, der veröffentlicht werden kann (noch nicht auf der Webseite)
• testing: enthält neu eingereichte Verbesserungen bzw. Veränderungen, die noch getestet werden müssen
• develop: hier wird aktuell gearbeitet, der aktuelle Arbeitsstand ist hier enthalten, keine Garantie für Lauffähigkeit

Daneben können auch weitere Branches zur Entwicklung genutzt werden.

Einreichen von Veränderungen

Veränderungen und Ergänzungen könnten über einen Pull-Request eingereicht werden. Dazu muss zuerst vom git ein eigener Fork gezogen werden. In diesem werden die Änderungen eingearbeitet. Dann lässt sich von diesem mit den Werkzeugen von gitlab ein Pull-Request auf das Original Repository erstellen. Personen, die regelmäßig an der Materialsammlung arbeiten, werden auf Anfrage ins Team aufgenommen und können dann direkt auf den passenden Branches arbeiten.

Docker

Die Docker-Version muss aktuell überarbeitet werden

Motivation

Für die Bearbeitung der Materialsammlung müssen neben einer LaTeX Installation auch einige weitere Softwarepakete installiert werden. Bei der Erstellung der Vorschaubilder für PDF-Dateien bei der Erzeugung der Webseite wird auf imagemagick zurückgegriffen. Genau dieses ist, um die mögliche Ausführung von Schadcode in PDF-Dateien zu verhindern, standardmäßig unterbunden. Es müsste also systemweit eine Sicherheitseinstellung geändert werden. Daher gab es die Überlegung all dieses in einem Docker-Container unterzubringen, der als Gast unabhängig vom darunterliegenden System ist.

Voraussetzungen und Vorbereitungen

Für die Nutzung des Docker-Containers wird folgendes benötigt:

• docker
• docker-compose
• SSH-Client

Im Verzeichnis docker/keys/ sollte eine Datei erzeugt werden mit der Endung .key, welche den öffentlichen RSA-Key enthält. Dieses macht ein einfaches Verbinden mit dem Container und die Nutzung von Git innerhalb des Containers möglich.

Erstellen/Starten des Docker-Containers

Gestartet wird der Docker-Container im Verzeichnis der Materialsammlung durch den folgenden Aufruf:

docker-compose up -d

Beim ersten Aufruf wird der Container auch komplett erstellt, was einige Zeit in Anspruch nehmen kann. Sollte es irgendwelche Änderungen an der Konfiguration des Containers geben, muss dieser neu gebaut werden. Dieses kann auch der Fall sein, wenn man einen weiteren RSA-Key hinzufügen will. Durchführen kann man diese Aktio durch

docker-compose build

oder wenn er direkt auch gestartet werden soll mit:

docker-compose up -d --build

Nach der Beendigung der Arbeit mit dem Docker-Container lässt sich dieser mit folgendem Befehl wieder herunterfahren:

docker-compose down -v

Verbinden mit dem Docker-Containers

Ein aktiver Docker-Container für die Materialsammlung lässt sich per SSH über den Port 15000 auf dem lokalen System erreichen. Der Benutzer ist matsam. Als Passwort ist pass gesetzt, was bei der Verwendung von einem RSA-Key aber nicht nötig ist. Ein Aufruf in einem Terminal würde dann wie folgt aussehen:

ssh matsam@localhost -p 15000

Das komplette Verzeichnis der Materialsammlung befindet sich im Verzeichnis matsam direkt im Homeverzeichnis. Es wurde als externes Verzeichnis gemountet und es ist somit keine Kopie. Alle Änderungen an Dateien in diesem Verzeichnis gelten auch außerhalb des Docker-Containers.

Erstellung der Webseite

Vorbereitung

Zunächst sollten sämtliche Materialien in folgender Struktur vorliegen:

materialien/thema/Dateien

Module benötigen eine daran angelehnte Struktur:

module/thema/Dateien

Eingelesen werden LaTeX-Dateien (*.tex) und dazugehörige gitfile-info-Dateien (*.gfi). Einzubindende Dateien müssen explizit ausgewiesen worden sein. Außerdem müssen entsprechende PDF-Dateien in der aktuellen Fassung vorliegen.

Hinweis: Bisher wird weder die Aktualität von gitfile-info noch der Status des Repositories berücksichtigt. Auch werden die PDF-Dateien nicht kontrolliert. Diese müssen zuvor eingestellt worden sein. Vor allem muss bisher die Aktualität bzgl. git-fat händisch per fat pull erstellt werden.

Konfiguration

Die Datei bin/ddipubWeb.cfg enthält notwendige Konfigurationen. Diese sind bereits auf die momentane Struktur angepasst worden. Darin werden die Pfade, sowie Suffixe etc. festgelegt.

Aufruf

Das Script sollte jeweils aus der Wurzel des Repositories heraus aufgerufen werden. Sollte eine eigene Verzeichnisstruktur verwendet werden, müssen die Pfade in der Konfiguration ggfs. angepasst werden. Für weitere Hinweise siehe

bin/ddipubWeb.py help

bzw. :doc:`ddipubWeb`, :doc:`ddipubMaterial` und :doc:`ddipubModule`.