# Beispielprojekte mit GitLab CI/CD von Fabian Gabel
Auf dieser Seite möchte ich unter dem Motto einige meiner GitLab CI/CD Beispielprojekte vorstellen.
Ich freue mich sehr über Rückmeldungen. Vielleicht habt ihr ja auch Projekte, die ihr hier ergänzen oder mit mir diskutieren wollt.
---
## Inhaltsübersicht
| \# | Name | Beschreibung | Eingesetzte Tools|
|--------|------|------ | ----|
|1. | [LaTeX Kick-Start](#kick) | In weniger als 5 Min ein CI/CD für $\LaTeX$ Dokumnte erstellen. | [`docker`](https://de.wikipedia.org/wiki/Docker_(Software)), [`latexmk`](https://mg.readthedocs.io/latexmk.html) |
|2. | [Jus`TeX`ercises](#texercise) | $\LaTeX$ Aufgabensammlung ohne Makros mit hyperlinked Tags, automatischer Kompilierung, erleichterte Einbindung und Pflege bestehender Aufgaben. | `docker`, `latexmk`, `markdown`, `grep/sed`, [`regex`](https://de.wikipedia.org/wiki/Regul%C3%A4rer_Ausdruck), `pandoc` |
|3. | [`GitLab`oratory](#research) | Unit Tests für Octave/MATLAB-Programmcode in Pipeline, automatische Grammatik und Rechschreibprüfung, unterschiedliche Builds je nach Journal, Nutzungszweck der Publikation | `docker`, `latexmk`, `grep/sed`, `regex`, `pandoc`, [`aspell`](http://aspell.net/), [`textidote`](https://sylvainhalle.github.io/textidote/), [`gnu-octave`](https://www.gnu.org/software/octave/index) |
|4. | [Resarch Topics Integration in Institute Webpage](#webpage) | Automatische Einbindung von Forschungsthemenbeschreibungen in .md auf die Institutswebseite (Demo Prototyp/*proof-of-concept*) | `docker`, `grep/sed`, `regex`, `wget`, `markdown`, `HTML`, `pandoc`, `GitLab Pages` |
* Das [`GitLab`oratory](#gitlaboratory) erweitert diesen Ansatz um weitere im Forschungs-/Publikationsprozess nützliche Tools (Rechschreibprüfung, Pre-/Postprocessing der Texdateien etc.)
---
## JusTeXercises <a name="texercise"></a>
Privates Repo (Bei Interesse füge ich euch gerne hinzu): [https://collaborating.tuhh.de/e-10/exercises_collection]()
### Idee
*[Single Source of Truth](https://de.wikipedia.org/wiki/Single_Point_of_Truth)(STOD) für die am Institut erstellten und in der Lehre/Klausuren eingesetzten Übungsaufgaben.
* Copy+Paste: Aufgaben enthalten keine nutzerdefinierten Makros und lassen sich in ein bereits existierende TeX Dokumente einbinden ohne dabei Fehler zu erzeugen.
* Automatisch generierte Liste aus Schlüsselwörtern, mit der man gezielt nach Aufgaben suchen kann.
### Use Cases
#### Use Case 0: Eine Mitarbeiterin kennt die Datenbank nicht
> \[**Mitarbeiterin**\]: *Ich überlege die Datenbank nicht, wo erhalte ich einen Überblick über die Aufgaben?*
> \[**JusTeXercises**\]: *Direkt auf der Hauptseite sind zur jeweiligen Veranstaltung GitLab Artefakte verlinkt. Jedes Artefakt besteht aus einer einzelnen `.pdf`-Datei, die alle Übungsaufgaben enthält. So kannst du dir einen Überblick über die verfügbaren Aufgaben machen.*
#### Use Case 1: Eine Mitarbeiterin bereitet ein wöchentliches Übungsblatt vor und sucht nach passenden Aufgaben.
> \[**Mitarbeiterin**\]: *In welchem **Semester**, welcher **Veranstaltung** und **von wem** wurde eine Übungs-/Klausuraufgabe gestellt?*
> \[**JusTeXercises**\]: *Jede `.tex`-Datei verfügt über einen Header mit Metainformationen, die von der Erstellerin der Aufgabe gesetzt wurden:
> \[**JusTeXercises**\]: *Im Quellcode sieht das dann so aus:*
> \[**JusTeXercises**\]: *Über einen Klick z.B. auf den Hyperlink [`[set-theory]`](https://collaborating.tuhh.de/search?utf8=%E2%9C%93&search=[set-theory]&group_id=&project_id=6328&scope=&search_code=true&snippets=false&repository_ref=master&nav_source=navbar)* sucht dir GitLab alle Aufgaben in dem Repository heraus, die dieses Tag besitzen.
#### Use Case 2: Modifikation bestehender Aufgaben
> \[**Mitarbeiterin**\]: *Ich habe einen Fehler entdeckt und möchte die Aufgabe korrigieren*.
> \[**Mitarbeiterin**\]: *Ich möchte die Aufgabe korrigieren erweitern*.
> \[**JusTeXercises**\]: *Durch einen Klick auf den Tag [`001.tex`](https://collaborating.tuhh.de/e-10/exercises_collection/-/blob/master/stochastics/001.tex) gelangst du direkt zum Quelltext der Aufgabe im Repository und kannst direkt in der Online-IDE den Fehler korrigieren (ggf. Forking+Merge-Request)*:
#### Use Case 3: Erweiterung der Datenbank um neue Aufgaben
> \[**Mitarbeiterin**\]: *Ich möchte eine neue Aufgabe zur Datenbank hinzufügen*.
> \[**JusTeXercises**\]: *Kein Problem. Funktioniert wie* `Use Case 3` *mit dem Unterschied, dass eine neue Aufgabe erstellt wird. Nachdem die Aufgabe ge`push`t wurde, werden Übersichts-pdf und die Taglist automatisch entsprechend deiner Angaben erweitert.*
### Baustellen
* Falls sinnvoll, eine `mysql` Datenbank aus den Tags etc. erstellen, die schneller lokal oder auf einem Webserver durchsucht werden kann.
### Erfahrungen und Nützliche Links
* Bei bereits bestehenden Aufgaben, lassen sich viele Makros direkt über ein [Perl oder Python Skript](https://tex.stackexchange.com/a/677300) ersetzen:, s.a. [replace-commands.pl](https://collaborating.tuhh.de/e-10/exercises_collection/-/raw/master/stochastics/replace_commands.pl)
* Die übrig bleibenden komplizierteren Makros lassen sich schnell über [VIM](https://de.wikipedia.org/wiki/Vim)-skripte oder [`sed`](https://de.wikipedia.org/wiki/Sed_(Unix)) entfernen. Beipsiel:
*[TeXtidote](https://github.com/sylvainhalle/textidote) Grammatik Check, *German false friends*, etc.
* Automatisiertes Postprocessing von TeX-Dateien
* Setzen von Metainformation zum Erstellungsprozess (`git-ref`, `git-sha`) im .pdf und .tex
* Auflösen aller `\include{}`s
* Löschen aller Kommentare im Quelltext
* Separate Bereitstellung der TikZ Grafiken
* Continuous Delivery
* TeXtidote output (funktioniert leider noch nicht auf collaborating.tuhh.de)
* .pdf zum Eigengebrauch
* .tex Datei für ArXiV Upload
* pdf Datei für Einreichung bei Journal (Operators & Matrices)
### Baustelle
* Leider funktioniert das Docker Image mit TeXtidote nicht mit dem Shared GitLab Runner `tanis` der TUHH. Auf GitLab.com funktioniert es jedoch problemlos. Das Problem könnte am ["Executor"](https://docs.gitlab.com/runner/executors/README.html) des Runners liegen.
---
## Resarch Topics Integration in Institute Webpage <a name="webpage"></a>
* 3 Min Rundgang Video: [https://media.tuhh.de/e10/gabel/research-topics/video1_rundgang.mp4](https://media.tuhh.de/e10/gabel/research-topics/video1_rundgang.mp4)
* Public Repository: [https://collaborating.tuhh.de/cfg0846/research-topics-mat-tuhh](https://collaborating.tuhh.de/cfg0846/research-topics-mat-tuhh)
* Die vom Repo ausgelieferte Website auf GitLab pages: [https://fabiangabel.gitlab.io/research-topics-mat-tuhh/](https://fabiangabel.gitlab.io/research-topics-mat-tuhh/)
