Newer
Older
# 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

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:
> \[**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)*:
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
#### 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
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
### 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/)