Voraussetzung:
- Docker muss installiert sein und laufen
- Linux oder MacOS (Windows habe ich nicht getestet)
- Dokumentation nach den offiziellen TYPO3 Vorgaben (siehe how-to-document-an-extension)
Schritt für Schritt
Schritt 1: Docker Image starten und Befehl in Terminal verfügbar machen
Terminal öffnen und Befehl ausführen im übergeordneten Verzeichnis der Dokumentation ausführen:
source <(docker run --rm t3docs/render-documentation show-shell-commands) Schritt 2: Dokumentation rendern
Wenn ich die Dokumentation als HTML betrachten möchte, führe ich folgenden Befehl aus:
dockrun_t3rd makehtml
Als Ergebnis erhält man den HTML Output im Verzeichnis: /Documentation-GENERATED-temp/Result/project/
Wenn das ganze als PDF erzeugt werden soll, müssen folgende Befehle ausgeführt werden:
dockrun_t3rd makeall
dockrun_t3rd makehtml -c make_latex 1 -c make_pdf 1 Damit wird neben dem HTML output auch eine Latex Ausgabe erzeugt, die im dritten Schritt verwendet wird.
Schritt 3: Umwandlung zu PDF
Zum Schluß werden noch drei weitere Befehle abgesetzt, um das PDF zu generieren.
mkdir -p Documentation-GENERATED-temp
docker run --rm \
-v $(pwd):/PROJECT:ro \
-v $(pwd)/Documentation-GENERATED-temp:/RESULT \
t3docs/render-documentation:develop \
makeall -c jobfile /PROJECT/Documentation/jobfile.json
docker run --rm \
-v $(pwd)/Documentation-GENERATED-temp/Result/latex:/RESULT \
--workdir="/RESULT/" \
thomasweise/docker-texlive-full:latest \
"./run-make.sh" Das Ergebnis befindet sich dann im Verzeichnis: /Documentation-GENERATED-temp/Result/latex/PROJECT.pdf
Fazit
Mit Hilfe der Docker Umgebung lassen sich nicht nur PDF Dateien rendern, sondern vor allem auch die Dokumentation einer TYPO3 Extension sinnvoll vorabtesten. Das Rst Format ist zwar aufwändiger als Markdown, bietet aber jedoch viel mehr Möglichkeiten eine umfassende Dokumentation mit Naviagtion und Querverlinkungen zu erzeugen.
