beispielprojekte-fabian-gabel.md

# 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` |

---


## LaTeX Kick-Start <a name="kick"></a>

[https://collaborating.tuhh.de/cfg0846/latex-kick-start](https://collaborating.tuhh.de/cfg0846/latex-kick-start)

### Idee

Schnell und unkompliziert `.tex`-Dokumente auf GitLab kompilieren und anderen zur Verfügung stellen. Das Repository kann entweder
* als Bauplan für Modifikationen dienen: `gitlab-ci.yml` *mutatis mutandis* übernehmen, und GitLab-Runner, Badges etc. anpasen

 oder auch

 * Ausgangspunkt für ein eigenes Projekt sein: `git clone` und GitLab-Runner etc. aktivieren.

In beiden Fällen, sollte nach nicht mehr als 5 Min nach jedem `git push` automatisiert ein aktuelles .pdf-Dokument bereitliegen und über eine Plakette

![](https://img.shields.io/badge/Download-PDF-blue)

herunter geladen werden können.

### Weiterführende Ideen

* 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](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:

![](img/exercise-tags.png)

> \[**JusTeXercises**\]: *Im Quellcode sieht das dann so aus:*

```latex
\begin{exercise}[Sets, Products, Functions]
%##################################################
% Filename: 001.tex
% Author: Fabian Gabel <fabian.gabel@tuhh.de>
% Comments:
% Tags: [stochastics], [ss2020], [group-exercise], [lang-en], [c-seifert], [set-theory]
%##################################################
...
```

> \[**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)*:

![](img/edit-ex.png)


#### 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:
```latex
% das Nutzermakro
\DeclarePairedDelimiter{\ceil}{\lceil}{\rceil}

...

% wurde hier eingesetzt
Let $A_k = \{\ceil{(k - 1)/2}\}$ ...

% und wird mittels VIM-Makro oder sed-Kommando zu

Let $A_k = \{\lceil (k - 1)/2 \rceil\}$ ...
```

--- 

## `GitLab`oratory <a name="research"></a>

* Beispiel Repository: URL
* Privates Repository (bei Interesse gerne anfragen): [https://collaborating.tuhh.de/cfg0846/periodschr](https://collaborating.tuhh.de/cfg0846/periodschr)

### Idee

* Gesamter Forschungsoutput, reproduzierbar in an einer Stelle (SSOT)
* Immer ein pdf Griffbereit
* Keine Backups über Cloudordner

### Artefakte 
![](img/badge-list.png)

### Bestandteile der CI/CD Konfiguration:


* Automatisierte Qualitätssicherung
    * Unit Test Suite für Programmcode, auf dem Resultate des Papers basieren
    * Suche nach unerwünschten Keywords im .tex (`\todo{}`)
    * [Aspell](http://aspell.net/) basierte Rechtschreibprüfung
    * [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/)