PHP-Dokumentation mit ApiGen

Schluss mit diesen Doxygen-Wüsten. Eine Dokumentation sollte nicht nur informativ sein, sondern auch Spaß machen. Bei meiner Arbeit an Clanpress habe ich ApiGen kennen gelernt. ApiGen ist ein Dokumentations-Generator der (derzeit) auf einem Subset der PHPDoc-Notation basiert. Wer auf der Suche nach einem Tool ist, mit dem man eine übersichtliche Dokumentation aus seinem PHP-Code generieren kann, die auch noch gut aussieht, sollte einen Blick riskieren.

ApiGen wird derzeit auf Github gehostet und ist als Composer-Package verfügbar. Dementsprechend erfolgt die Installation am besten über Composer. Ob nun lokal im Projekt oder global ist Euch überlassen:

$ composer require apigen/apigen

Die Generierung der Dokumentation erfolgt über das CLI. Achtet hier darauf, dass die Composer-Binaries in Eurer $PATH-Variable (in Eurer Shell) eingerichtet sind. Das gilt natürlich nur, wenn Ihr das Tool global installiert habt.

Eure Dokumentation generiert Ihr dann so:

$ apigen generate your-folder --destination docs

Oder so, wenn Ihr mehrere Ordner verarbeiten wollt:

$ apigen generate folder1 folder2 --destination docs

Über --destination gebt Ihr den Zielordner an, in dem Eure Dokumentation abgelegt werden soll. ApiGen funktioniert am besten bei OOP. Mit unstrukturierten PHP-Dateien kann ApiGen wenig anfangen. Template-Dateien kann man darum zum Beispiel nicht in der Dokumentation wieder finden.

Wem das Standard-Verhalten von ApiGen nicht gefällt, der kann eine apigen.yml in das Root-Verzeichnis seines Projektes legen. Mit dieser könnt Ihr unter anderem das verwendete Template, die Source-Dateien, sowie diverse weitere Optionen konfigurieren. Die Konfiguration für Clanpress sieht beispielsweise so aus:

templateTheme: 'default'
source:
  - components
  - includes
  - modes
  - clanpress.php
annotationGroups: ''
accessLevels:
  - public
  - protected
  - private
internal: true
tree: true
download: true
php: false
todo: true
deprecated: true

Verwenden könnt Ihr die Konfiguration dann so:

$ apigen generate --config apigen.yaml --destination docs

Details zu den einzelnen Optionen und der weiteren Benutzung könnt Ihr der Dokumenation von ApiGen entnehmen. Mir persönlich hat das Tool bei der Entwicklung von Clanpress sehr geholfen den Überblick zu behalten.