Deployment von TYPO3-Extension-Dokumentation

Bei der Entwicklung von TYPO3-Extensions nimmt die Dokumentation zwar nur einen kleinen Teil ein, ist aber im Nachgang ziemlich wichtig.

Die Dokumentation der Erweiterungen wird von unterschiedlichen Zielgruppen benutzt:

  • Redakteure, die meist nicht in der Planung der Extensions involviert sind, aber diese letztendlich im TYPO3 einsetzen müssen. Diese benötigen Screenshots, Konfigurationsbeispiele und Erklärungen über die Möglichkeiten der Erweiterung.
  • Andere Agenturen, die auch mit am TYPO3 arbeiten. Diese benötigen API-Dokumentationen und eine Grobübersicht über die jeweilige Erweiterung zu erhalten.
  • Eigene Mitarbeiter, die neu zum Team hinzukommen oder nach 2 Jahren wissen wollen, was die Erweiterung eigentlich macht, und welche Anforderungen dazu geführt haben, dass der Code aussieht wie er aussieht.

Zentrale Pflege

Dokumentation kann an unterschiedlichen Stellen und in verschiedenen Formaten vorliegen:

  1. E-Mail zu Projektabschluß an den Kunden
  2. Dokumentationsordner des Projekts, als Textdokument (.odt oder .doc), im eigenen Wiki oder im Wiki des Kunden
  3. In der Extension als doc/manual.sxw oder Documentation/Index.rst, wie es bei typo3.org üblich ist.

Die erste Variante – E-Mail – ist die unflexibelste und unsichtbarste Art der Dokumentation. Updates sind schwer möglich, und außer dem Empfänger weiß niemand davon. Bei mehreren Entwicklern nur von einer Person pflegbar.

Die Datei im Dokumentationsordner des Projekts oder im Wiki ist von mehreren Personen pflegbar, allerdings „zu weit“ vom Code entfernt. Wenn die Extension angepasst wird, muss man immer erst in ein anderes Tool wechseln, welches nicht in den normalen IDE-Git-QA-Deployment-Workflow integriert ist.

Da die Dokumentation bei uns von den Entwicklern selbst geschrieben wird, lag es nahe, die Dokumentation direkt mit im Git-Repository der jeweiligen Erweiterung zu pflegen.

Weiterhin ist es sehr wichtig, die Dokumentation im normalen Entwicklungsprozess mit in Code-Diffs ansehen zu können, und konkurrierende Änderungen aus verschiedenen Branches einfach zu mergen.

Diese Anforderungen schränkte die Auswahl des Dokumentationsformats auf plaintext-basierte Formate ein.

Wir hatten die Wahl zwischen folgenden Optionen:

  • Docbook. XML-basiert und damit sehr ausführlich zu schreiben. Weiterhin brauchen wir nur einen Bruchteil von dessen Funktionalität.
  • Markdown. Hier ist nur sehr wenig Markup zu schreiben. Generell sind die Möglichkeiten jedoch sehr eingeschränkt – es gibt z.B. keine Definitionslisten oder Tabellen, wenn man von Inline-HTML absieht.
  • reStructuredText (rST). Beim Schreiben ist etwas mehr Syntax notwendig als bei Markdown, aber man kann auch viel mehr ausdrücken.

Letztendlich haben wir uns für rST entschieden, weil wir es einen guten Kompromiss zwischen Features und Schreibbarkeit darstellte.

Inzwischen wird rST auch bei TYPO3.org favorisiert und für die offizielle Dokumentation eingesetzt. Damit gibt es einige Tools, die rST-basierte Dokumentation direkt im TYPO3 anzeigen kann, und wir müssen uns nicht umstellen, wenn wir zwischen kundenspezifischen und Open-Source-Extensions wechseln.

Deployment zum Kunden

Beim Kunden liegt die Dokumentation zentral in einem Wiki, weshalb die Dokumentation als .rst-Datei im Git-Repository der Extension nicht sehr nützlich ist.

Die von den docutils angebotenen Standardformate (HTML, S5, Latex, OpenDocument Text, PDF) halfen hier nicht wirklich weiter. Wir konnten zwar ein PDF generieren und das an eine Wiki-Seite anhängen, hatten damit aber einen Formatbruch und reduzierte Durchsuchbarkeit.

Abgesehen davon sollte das Deployment der Dokumentation komplett automatisiert werden; das manuelle Anhängen des PDFs würde da nur stören.

rst2confluence

Einer unserer Kunden setzt Confluence als Wikisoftware ein, weshalb wir zuerst eine Möglichkeit benötigten, reStructuredText in Confluence-Markup zu konvertieren.

Kenichiro Tanaka hatte das Tool rst2confluence gebaut, welches einfaches rST-Markup konvertieren konnte. Mit zunehmender Zahl an dokumentierten Extensions reichte dessen Funktionalität allerdings nicht mehr aus, so dass wir einige Erweiterungen vornehmen mussten. 90% der Funktionalität wurde inzwischen von uns beigesteuert.

Inzwischen ist es möglich, sehr komplexe rST-Dokumente zu rendern. Auch sind wir an dem Punkt, dass wir um Bugs in Confluence herumarbeiten müssen – ein Zeichen dafür, dass die Formatabdeckung inzwischen ziemlich komplett ist 🙂

deploy-rst

Die Erstellung von Confluence-Markup ist nicht alles beim Deployment; der Text muss auch automatisch im Wiki landen.

Basis für den Dokumentations-Deploymentprozess ist das Confluence Command Line Interface von Bob Swift, mit dem man per Kommandozeile Seiten im Confluence-Wiki verändern kann.

Das allein reicht leider nicht; wir müssen auch irgendwo vermerken, auf welche Seite im Wiki die Dokumentation deployed werden soll. Weiter sollte auch nicht jedes Mal das Benutzerpasswort fürs Wiki eingegeben werden müssen.

deploy-rst ist das Ergebnis der Entwicklung: Es liest die in den Metadaten des rST-Dokuments hinterlegten Einstellungen wie Wiki-Space und Seite aus, konvertiert rST nach Confluence-Markup und aktualisiert die Wikiseite mit dem neuen Inhalt.

Installation

Einfach per PEAR-Installer:

$ pear channel-discover pear.nrdev.de
$ pear install nr/deployrst-alpha

Einrichtung des Confluence-Benutzernamens und Passworts:

$ cp `pear config-get cfg_dir`/DeployRst/config.php.dist ~/.config/deploy-rst
$ emacs ~/.config/deploy-rst
.. change user and password

Verwendung

Die Metaangaben in rST einfach am Anfang nach der Überschrift einfügen:

.. meta::
   :deploy-target: confluence
   :confluence-host: http://confluence.example.org
   :confluence-space: IT
   :confluence-page: rstpagetest

Jetzt einfach deployen:

$ deploy-rst README.rst

phingTypo3ExtdataExtract

Neben der Dokumentation an sich sollten auf der Wikiseite auch gleich Informationen über Version, verantwortliche Entwickler und Abhängigkeiten zu anderen Erweiterungen zu sehen sein.

Diese Daten sind bei TYPO3-Extensions in der ext_emconf.php hinterlegt, und wir benutzen diese auch, um unsere Dokumentation beim Deployment zu aktualisieren.

Dazu fügen wir in der README.rst zwei Zeilen hinzu:

.. BEGIN ext_emconf.php
.. END ext_emconf.php

Mit Hilfe des phing-Tasks phingTypo3ExtdataExtract packen wir die Extensioninformationen zwischen die beiden Marker, bevor die Dokumentation deployed wird.

Verwendung

Dokumentations-Update-Task in der build.xml für phing:

<target name="updatereadme"
        description="Update README.rst from ext_emconf.php">
    <t3emconf propertyName="extrst" format="rstaida"/>
    <reflexive>
        <fileset dir=".">
            <include name="README.rst"/>
        </fileset>
        <filterchain>
            <replaceregexp>
                <regexp
                    pattern="\.\. BEGIN ext_emconf\.php.+.. END ext_emconf.php"
                    replace=".. BEGIN ext_emconf.php&#10;&#10;${extrst}&#10;&#10;.. END ext_emconf.php"
                    modifiers="s"
                    />
            </replaceregexp>
        </filterchain>
    </reflexive>
</target>

Zusammenfassung

Die Pflege der Extensiondokumentation als rST-Dokument hat sich bei uns bewährt. Das rST-Format ist einfach zu schreiben, zu pflegen und integriert sich gut in unseren Git-Workflow.

Mit den Tools rst2confluence und deploy-rst ist es uns möglich, Dokumentation innerhalb von Sekunden zum Kunden ins Wiki auszurollen.

 

Diesen Artikel kommentieren

Autor
Dies ist nur ein Gravatar
Christian Weiske
Archiv
Mai 2016
M D M D F S S
   
 1
2345678
9101112131415
16171819202122
23242526272829
3031  
Letzte Kommentare