========================
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`.