Dokumentation
reST
Damit's nicht langweilig wird wieder ein neues Format: reST - restructured Text. Zum Rendern unter OSX ist einiges zu tun, aber ich hab's nun geschafft mit folgenden beiden Anleitungen
http://wiki.typo3.org/Rendering_reST_on_Linux#Mac_OS_X_and_MacPorts:_conflicting_Python_install
http://wiki.typo3.org/New_reST_Project_with_Sphinx
Installation
Hier meine Schritte:
# yaml libraries
cd /usr/local/src
wget pyyaml.org/download/libyaml/yaml-0.1.4.tar.gz
tar xzf yaml-0.1.4.tar.gz
cd yaml-0.1.4
./configure
make
make install
# yaml for python
easy_install pyyaml
easy_install -U Sphinx
# TYPO3 documentation template
cd /Rsys_Source/documentation
mkdir reST
git clone git://git.typo3.org/Documentation/RestTools.git
cd RestTools//ExtendingSphinxForTYPO3
python setup.py install
Erzeugen der Dokumentation
Zunächst initialisieren (Makefile erstellen, Projektname etc.):
cd /Rsys_Source/documentation/rsysemployment
sphinx-quickstart
# Auswählen: Separate source and build directories (y/N) [n]: y
Verlinken der Dokumente:
cd source
ln -s /Rsys_Source/rsysemployment/Readme.rst
Dann einige Anpassungen in source/conf.py:
html_theme = 'typo3sphinx'
html_theme_path = ['/Rsys_Source/documentation/reST/RestTools/ResourcesForSphinxAndDocutils/res/sphinx/themes/']
Und erzeugen mit:
make html
Eclipse
Das Erzeugen geht auch in Eclipse als Builder:
Dann noch den Pfad anpassen:
Beim Build wird dann die Dokumentation gerendert.
rst2pdf
Um PDFs zu erzeugen gibt es rst2pdf - Download unter https://code.google.com/p/rst2pdf
cd /usr/local/src
wget code.google.com/p/rst2pdf/downloads/detail
cd rst2pdf-0.93
python setup.py install
Die rst2*** Dateien liegen dann unter /usr/local/bin - bei mir funktioniert nur die rst2pdf problemlos, die anderen (*rst2*.py) haben Probleme beim Rendern. Aber das hier klappt:
rst2pdf mydocument.txt -o mydocument.pdf
Zum Html erzeugen ist sowieso Sphinx besser geeignet. Siehe Artikel eins höher.
Dokumentation schreiben
Um Dokumentation in ExtBase Extensions oder FLOW Packages zu schreiben kommt das DocBook Format zum Einsatz. Eine gute Anleitung als Video ist hier zu finden:
http://flow3.typo3.org/documentation/videos/writing-docbook-manuals-for-typo3-t3cast-011/
Der empfohlene Editor ist XmlMind - kostenlos erhältlich für Verwendung in OpenSource Projekten. Zu finden unter http://xmlmind.com/xmleditor/download.shtml. Allerdings hat nur die kostenpflichtige Version die Möglichkeit zum Rendern als HTML oder PDF (im "Convert Document" Menü, welches der freien Version fehlt).
Dokumentation Rendern mit FLOW3
Um aus dem DocBook XML PDF oder HTML zu generieren braucht es wiederum Tools. Ich habe es mit den Tools aus FLOW3 versucht. Dazu Braucht man die 2 Packages DocBookXSLNS und DocTools.
Download:
cd FLOW3-1.0.0-alpha11-build32/Packages/Application
svn export svn.typo3.org/FLOW3/Packages/DocBookXSLNS/trunk DocBookXSLNS
svn export svn.typo3.org/FLOW3/Packages/DocTools/trunk DocTools
Aktivieren:
cd FLOW3-1.0.0-alpha11-build32
./flow3 package activate DocTools
./flow3 package activate DocBookXSLNS
Render manuals:
...für Extbase unpraktisch, da nur in Flow Packages gesucht wird. Also werde ich zu einem späteren Zeitpunkt hier fortfahren, wenn FLOW3 im Vordergrund steht, momentan ist dies noch ExtBase.
Dokumentation Rendern mit externen Tools
Als Beispiel nehme ich mal das DocBook XML File Introduction.xml aus dem FLOW3 Package.
HTML erzeugen mit Saxon
Saxon installieren
Download von http://sourceforge.net/projects/saxon/files/Saxon-B/saxonb8-5-1.zip/download
Entpacken z.B. in /usr/local/saxonb8-5-1
Docbook installieren
/opt/local/bin/port install docbook-xsl
Die DocBook stylesheets sind nun unter /opt/local/share/xsl/docbook-xsl/xhtml/docbook.xsl
Rendern
java -jar /usr/local/saxonb8-5-1/saxon8.jar -o Introduction.html Introduction.xml /opt/local/share/xsl/docbook-xsl/xhtml/docbook.xsl
PDF erzeugen mit Apache FOP
FOP installieren
Download unter http://xmlgraphics.apache.org/fop/0.95. Entpacken in ein Verzeichnis (z.B. /usr/local/fop-1.0) und dort folgendes Aufrufen (siehe hierzu http://xmlgraphics.apache.org/fop/0.95/compiling.html):
ant package
PDF Rendern
Zunächst das fo erzeugen mit saxon:
java -jar /usr/local/saxonb8-5-1/saxon8.jar -o Introduction.fo Introduction.xml /opt/local/share/xsl/docbook-xsl/fo/docbook.xsl
Dann das PDF mit FOP:
./fop Introduction.fo Introduction.pdf
Skript
Hier alles zusammengefasst - erzeugt html und pdf Dateien. Aufruf: make_docbook.sh TestDocBook
#!/bin/bash
java -jar /usr/local/saxonb8-5-1/saxon8.jar -o $1.html $1.xml /opt/local/share/xsl/docbook-xsl/xhtml/docbook.xsl
java -jar /usr/local/saxonb8-5-1/saxon8.jar -o $1.fo $1.xml /opt/local/share/xsl/docbook-xsl/fo/docbook.xsl
/usr/local/fop-1.0/fop $1.fo $1.pdf