MkDocs
MkDocs generiert sowohl unsere Projekt- als
auch unsere Teamdokumentation. Die Dokumentation is meist Passwort
geschützt. Dass Passwort für die
Teamdokumentation findet sich in
Bitwarden unter
docs.svc.b5c.eu.
Dokumentation für das Schreiben von Dokumentation findet man beispielsweise im Documentation Guide von Write the Docs.
Installation
Installiere MkDocs sowie alle benötigten Plugins als normaler Benutzer (nicht als root). Hierzu erstellen wir zunächst ein Python Virtual Environment:
# Virtuelle Umgebung für MkDocs mit dem Namen `mkdocs_env` im Heimverzeichnis erstellen
cd ~
virtualenv mkdocs_env
# Virtuelle Umgebung mit dem Namen `mkdocs_env` aktivieren
source mkdocs_env/bin/activate
# MkDoc sowie benötigte Plugins in der virtuellen Umgebung installieren
pip install mkdocs mkdocs-render-swagger-plugin mkdocs-glightbox mkdocs-monorepo-plugin install mkdocs-material mkdocs-macros-plugin
Hinweis: Welche MkDocs Plugins im Detail benötigt werden findest du in unserem dockerfiles Repository.
Nutzung
Kommandozeile
Nun kannst du in deinem Projektverzeichnis MkDocs ausführen mittels:
# Wechsel in dein Heimverzeichnis und aktiviere die Virtuelle Umgebung `mkdocs_env` (falls nicht vorher bereits aktiviert)
cd ~
source mkdocs_env/bin/activate
# In das MkDocs Projekt wechseln
cd /pfad/zu/mkdocs-projekt/
# MkDocs starten
mkdocs serve
Troublshooting
Meldung your environment does not support jcef cannot use markdown editor bei Aufruf der Markdown-Vorschau in PhpStorm
Lösung:
```
installiere Paket jre-jetbrains
yay -S jre-jetbrains
mache jre-jetbrains zur standard Java-Umgebung auf deinem System
sudo archlinux-java set jre-jetbrains