Puppet: Manifest Dokumentation mit puppet doc / post-commit Hook

Wie ueberall im Leben bietet es sich auch an puppet Manifest Dateien zu dokumentieren. Die Dokumentation dort basiert auf rdoc. Die Syntax wird in der Puppet Manifest Documentation Wiki Seite unten ganz gut beschrieben. Hier ein paar Beispiele:

  1. Eine Testklasse mit Dokumentation davor. Wichtig ist, dass zwischen Ende der Dokumentation und Definition der Klasse KEINE Leerzeile ist, sondern die Kommentare bis direkt an die class test() {} Zeile gehen:
    Bildschirmfoto vom 2014-05-18 20:02:08
  2. Die einfachste Art- und Weise die Dokumentation zu lesen ist, diese auf der Kommandozeile auszugeben. Das tut man mit dem folgenden Befehl:
    puppet doc /path/to/manifest.pp

    Bildschirmfoto vom 2014-05-18 20:01:17

  3. Schoener zu lesen ist das ganze als HTML Seite. Ich persoenlich habe in dem GIT Repository in dem ich die Puppet Konfiguration verwalte einen post-commit Hook, der mir die Dokumentation erzeugt und in einem Verzeichnis ablegt, das mit Apache freigegeben ist. Der Aufruf dafuer ist in der post-commit Datei:
    puppet doc --all --mode rdoc --outputdir /var/www/example.org/puppetdocs/

    Und es sieht dann am Ende wie folgt aus:
    Bildschirmfoto vom 2014-05-18 20:02:44

    Wenn im Modul root Verzeichnis eine Datei README liegt, wird diese als Gesamtdokumentation fuer das Modul mit hinzugenommen.