Es war einmal ein Markdown Dokument

Man mag sich fragen, wie es zu dieser Situation kam.
Im Rahmen einer internen Weiterbildungsmaßnahme wird ein Code Style entwickelt. Der Code Style soll dabei sehr viel mehr Wert auf Sauberkeit und komprimierten Source Code
legen. Wir betrachten im Folgenden die Herausforderung, wie wir diesen Code Style für die
Entwickler und für andere interessierte zur Verfügung stellen.

Anmerkung: Der Code Style ist keineswegs offiziell bereits der neue Style Guide, in diesem Artikel geht es ausschließlich um die Art und Weise wie hier eine CI Pipeline aufgebaut wurde

Der Style Guide

Der Code Style an sich ist nah am Google Style Guide aufgebaut und wurde anfangs von mir und Merlin Osayimwen entwickelt und als offizieller Style Guide von vicuna.io veröffentlicht.
Für GommeHDnet wurde ein neuer Fork begonnen, weil nicht alle Vorschläge des vicuna.io style guides zu 100% auf unseren Anwendungsfall übertragen werden konnten.

Den Style Guide ausliefern

Nicht alle wollen mit einer Markdown-Datei arbeiten. Besonders nicht-Developer können Markdown selten viel abgewinnen. Von den entsprechenden Stellen wurde verlautbart, dass eine PDF weitaus praktischer wäre.
Und was tut man nicht alles? Alles für den Dackel, alles für den Club. Wir wollen also unseren Style Guide, der in Markdown geschrieben ist in eine PDF umwandeln. Möglichst wollen wir dabei weiterhin versionieren und eine History haben. Klingt nach einem Job für die GitHub Releases, oder nicht?

Markdown in PDF umwandeln

Für einen so doch trivial klingenden Anwendungsfall gibt es dann doch überraschend wenige Tools. Die Wahl fiel am Ende auf Pandoc, aufgrund des einfachen Command Line Interfaces und der zahlreichen unterstützten Format, für den Fall, dass gewisse Stakeholder ihr Meinung mal wieder schneller wechseln, als wir das gerne hätten.

Markdown am Fließband in PDF umwandeln

Da wir bei GommeHDnet von Natur aus eher gemütliche Entwickler sind wollen wir natürlich nicht den ganzen Tag vor dem Schreibtisch sitzen und unser Terminal mit dem Umwandeln von Markdown Dokumenten in PDFs quälen. Das hat automatisiert zu werden, immerhin schimpfen wir uns Informatiker. Wir brauchen also ein Build Tool für eine einfache CI/CD Pipeline.
Aufgrund guter Erfahrungen und der Nähe zu GitHub fiel die Wahl auf Travis CI.

Wir nehmen also eine simple Grund-Einstellung (.travis.yml):

1
2
dist: bionic
language: bash

Wir arbeiten mit bash und unsere auf Ubuntu bionic. Pandoc ist natürlich nicht vorinstalliert, wir installieren also die entsprechenden Pakete nach:

1
2
3
4
5
6
7
8
9
10
11
12
dist: bionic
language: bash

addons:
apt:
update: true
packages:
- lmodern
- texlive-latex-extra
- texlive-generic-recommended
- texlive-fonts-recommended
- pandoc

Außer pandoc brauchen wir noch lmodern als Schriftart und ein paar Libraries für den von uns verwendeten LaTeX Reader. Fehlt noch das eigentliche Build-Skript:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
dist: bionic
language: bash

addons:
apt:
update: true
packages:
- lmodern
- texlive-latex-extra
- texlive-generic-recommended
- texlive-fonts-recommended
- pandoc

jobs:
include:
- script: pandoc -t latex README.md -o style-guide.pdf

Dabei verwenden wir den LaTeX Reader und als output definieren wir die style-guide.pdf. Fertig ist die Pipeline. Die Style Guide PDF wird automatisch gebaut.

Vom Fließband raus in die Welt

Nun bringt es uns nicht viel, dass da eine PDF rumliegt, wir müssen damit auch etwas machen. Wir fügen also einen Deployment Schritt hinzu.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
dist: bionic
language: bash

addons:
apt:
update: true
packages:
- lmodern
- texlive-latex-extra
- texlive-generic-recommended
- texlive-fonts-recommended
- pandoc

jobs:
include:
- script: pandoc -t latex README.md -o style-guide.pdf

deploy:
provider: releases
file: style-guide.pdf
skip_cleanup: true
api_key:
secure: <encrypted GitHub Token>
on:
tags: true

Als Provider geben wir die GitHub releases an. Das einzige File, das uns interessiert ist die PDF vom Style Guide. Damit die nicht schon vor dem Deployment wieder weggeräumt wird, überspringen wir das clean up. Zum Schluss fügen wir einen API-Key hinzu und stecken ihn mit travis in eine sichere Variable, damit Travis CI an unsere GitHub Releases kommt und sagen dem Deployment, es soll sich zum Teufel scheren, es sei denn, es gibt eine neue getaggte Version.

Fertig!

Das Ergebnis lässt sich hier bewundern. Die Releases findet ihr hier.

Viel Spaß damit!

Felix Klauke

Felix Klauke