CI für Documentation-as-code

Hier sind ein paar nützliche Pipelines zur Überprüfung/Verarbeitung der Dokumentation, die wir in unseren CI-Build-Prozess integrieren können.

Markdown-Linting

Um den Markdown-Stil zu vereinheitlichen und defekte Links zu vermeiden, wird ein Markdown-Linter wie markdownlint dringend empfohlen. Wir können in der Markdown-Datei selbst oder in einer Projektkonfigurationsdatei festlegen, welche Regeln verwendet werden sollen. Diese Regeln werden dann sowohl vom Kommandozeilen-Tool als auch von der VS Code-Erweiterung beachtet.

Als Beispiel dient diese GitHub-Aktion, die markdownlint ausführt, um nach Fehlern zu suchen. Die Projektkonfiguration befindet sich in dieser Datei.

PDF-Generierung

Wie in diesem Artikel beschrieben, kann eine aktuelle PDF-Version der Dokumentation nützlich sein.

Diese GitHub-Action verwendet pandoc und weasyprint1, um eine PDF-Dokumentation zu erstellen und als Release zu veröffentlichen. Durch die Release-Veröffentlichung kann die neueste Version über den permanenten Link https://github.com/neshanjo/what2eat/releases/latest/download/architecture-documentation.pdf heruntergeladen werden.

  1. Die Action verwendet nicht pagedjs-cli, da die Installation von weasyprint auf dem GitHub-Runner über apt-get viel schneller geht als die npm-Installation von pagedjs-cli. ↩