Skip to content
Snippets Groups Projects
Commit 094e618b authored by Fabian Nuraddin Alexander Gabel's avatar Fabian Nuraddin Alexander Gabel :speech_balloon:
Browse files

transfer project md from other repo

parent d3c98704
No related branches found
No related tags found
No related merge requests found
# 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]()
### 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]()
### 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:
![](assets/images/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)*:
![](assets/images/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]()
### Idee
* Gesamter Forschungsoutput, reproduzierbar in an einer Stelle (SSOT)
* Immer ein pdf Griffbereit
* Keine Backups über Cloudordner
### Artefakte
![](assets/images/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/)
\ No newline at end of file
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment