dokumentation generator für mako??

[milili]

Hallo!

Ich möchte meine .mako templates dokumentieren.
(Die ganzen Kommentare die zu den Funktionen, Klassen etc. gehören extrahieren)
Ich habe ausführlich recherchiert und leider nur Generatoren gefunden die mit Python kompatibel sind.

Gibt es ne elegantere Lösung als mein mako template als Text einzulesen und nach def-s und doc-s durchzusuchen??

Gibt es evtl. einen Weg den Python Code zu erhalten before das template rendered wird?
(das .mako wird in python konvertiert)

Thx! Mili

[Dauerbaustelle]

Wenn du schon Dokumentation für deine Templates brauchst, sind sie viel zu komplex. Templates sollten nur die Darstellung bestimmen und keine Logik enthalten.

Lagere die Logik einfach in den Python-Code aus, dann hast du kein Problem mit anständiger Dokumentation.

[lunar]

@milili: Es gibt keine komfortable Möglichkeit, aus Mako-Templates Dokumentation zu extrahieren. Ich glaube auch nicht, dass Du direkt an den Python-Quelltext gelangen kannst, da Mako meines Wissens direkt in Bytecode übersetzt. Allerdings kannst Du mit den "module_*"-Parametern der "Template()"-Klasse bestimmen, wohin die generierten Module gespeichert werden sollen. Dann kannst Du diese Module vom Dokumentationsgenerator durchsuchen lassen, und erhältst – unter der Annahme, dass Mako die Docstrings tatsächlich beachtet – Dokumentation für Deine Templates.

Ich glaube allerdings nicht, dass diese Dokumentation sonderlich zielführend ist, da Du ja immerhin den generierten Python-Code dokumentierst und nicht das, was tatsächlich in den Templates steht. Dokumentiere die Templates lieber selbst, so wie beispielsweise in der Dokumentation von Sphinx.

Den Beitrag von Dauerbaustelle kannst Du getrost ignorieren, da Templates durchaus so komplex werden können, dass Dokumentation nötig, oder zumindest hilfreich ist.

[Dauerbaustelle]

Den Beitrag von Lunar kannst du getrost ignorieren. Templates sollten nicht so komplex werden, dass man sie umfangreich dokumentieren muss, um noch durchzublicken.

[DasIch]

Jedes Projekt welches nicht extrem trivial ist, also 2 oder mehr Templates hat, wird irgendwann Makros oder sowas wie Jinjas Blocks nutzen; dann macht es Sinn Templates zu dokumentieren.

Desweiteren hat niemand von umfangreicher Dokumentation gesprochen, es geht ja nicht darum Romane zu schreiben.

[milili]

Hallo nochmal!
Danke lunar für deine unerstützdenden Worte.
Ich habe schon angefangen mich mit Sphinx zu beschäftigen und hab es installiert usw. nur schaff ich es nicht ein html zu bilden.

Wenn ich $ make html eingebe meldet er das es diesen Befehl nicht gibt

sphinx-build -b html -d _build/doctrees . _build/html
make: sphinx-build: Command not found
make: *** [html] Error 127

Ich habe dann die directiories (in diesem fall -biuld) geändert, damit ich im Berzeichnis bin wo mein index file ist und sphinx eben installiert wurde.
Im gleichen Verezichnis exisitert sphinx-biuld.py.

und dazu kommt raus: sphinx-build: Command not found.

Was übersehe ich hier, bzw. was mache ich falsch??

Danke im Voraus!
Mili