Ich habe am 04.10.2015 die neue Version 1.1.0 von Mzeis_Documentation veröffentlicht.
Extension-Dokumentation im Backend lesen
Die Version 1.1.0 von Mzeis_Documentation kann die Dokumentation eines Moduls im Backend anzeigen.
Viele Entwickler (besonders in der Open-Source-Szene) liefern für ihre Module eine Dokumentation im Markdown-Format mit.
Markdown erlaubt es Texte auf einfache Weise zu formatieren und ist deswegen sehr beliebt. Das Problem ist allerdings, dass diese Formatierung nur in speziellen Programmen oder auf Plattformen wie GitHub automatisch vorgenommen wird. Außerdem fehlt eine zentrale Stelle, an der die Markdown-Dokumentation eines Shops gesammelt dargestellt wird.
Beide Probleme soll die neue Version von Mzeis-Documentation lösen. In 1.1.0 kann man nun nicht mehr nur selbst über das Backend eine Projektdokumentation verfassen, sondern auch die Markdown-Dokumentation der Module direkt im Backend lesen. Die Texte werden entsprechend formatiert und untereinander verlinkt. Auch die Suche kann mit der Modul-Dokumentation umgehen.
Damit ein Modul im Dokumentations-Backend angezeigt wird, muss es entsprechend vorbereitet werden. Es gibt zwar einige (sicherheits-)technische Einschränkungen z.B. bei der Anzeige von Bildern innerhalb der Dokumentation, doch trotzdem hoffe ich, dass diese neue Funktionalität dem einen oder anderen das Magento-Leben erleichtert.
Markdown auch in der Projektdokumentation
Das zweite Feature von 1.1.0 ist, dass Markdown nun auch in der Projektdokumentation verwendet werden kann. Wie erwähnt setzen gerne Entwickler gerne darauf, weil die Syntax mit der die Formatierung gesteuert wird einfacher zu handhaben ist als HTML. Auch Synergie-Effekte mit bestehender Markdown-Dokumentation sind zu erwarten, weil der Text nicht händisch umformatiert werden muss.
Mzeis_Documentation v1.1.0 ausprobieren
Neugierig geworden? Die Anleitung zur Installation von Mzeis_Documentation über Composer findet sich bei GitHub.
I like the idea, but would be nice if you could connect it to a wiki, e.g. github by simple adding a node to the /etc/config.xml:/global/docus/{module}/src = https://github.com/mzeis/Mzeis_Documentation/wiki, so that the docu is the latest version and can be updated without updating the module.
Sry, I only briefly look at it, maybe you have something similar working
Thank you for the feedback! How would the integration between the wiki and the Magento backend work?
My understanding was that, at least for github, the wiki for any project is just a simple repository (e.g. https://github.com/mzeis/Mzeis_Documentation.wiki.git)
I am not sure if it is a far catch trying to access the data from git using php, though git libraries do exist. That way it can cache an keep an update of the current version.
I don’t know much about the github API, maybe there is a better way, but I like to think that there is 🙂