Seit einiger Zeit bietet die TYPO3 Infrastruktur die Möglichkeit, Dokumentationen im reStructuredText (reST) Format zu erstellen. Damit wurde das alte Star-Office Format .sxw, das bislang der Standard für Extensiondokumentation war deprecated.

Dokumentationen aller Extensions, die im TYPO3 Extension Repository sind und eine Dokumentation besitzen werden bereits automatisch auf docs.typo3.org gerendert. Ein Nachteil dieses Vorgehens ist, dass nicht alle Extensions im TYPO3 TER vorhanden sind, da sie in Repositorys wie GitHub oder Bitbucket liegen. Nun kommt das SaaS Projekt Read the Docs ins Spiel, das Dokumentationen im Markdown oder reST Format nach jedem Push in das Sourcecode Repository erstellt. Voraussetzung ist also, dass die Dokumentation TYPO3-konform im reST-Format vorliegt. Dazu wird ein Verzeichnis Documentation in der Extension benötigt, in dem eine Konfigurationsdatei conf.py für das Rendering von Sphinx Dokumentationen in Read the Docs liegt. Diese Datei hat im Kern den Folgenden Aufbau:

Nun muss die Extension nur noch Read The Docs bekannt gemacht werden, damit dies auf entsprechende Änderungen reagiert und die Dokumentation neu baut.

Unser Beispielprojekt

Sehr gelungen ist, dass auf jeder Seite der gerenderten Dokumentation ein Link ist “Edit on GitHub”, mit dem man direkt in die Quelldatei springen und (die nötigen Rechte vorausgesetzt) editieren kann.