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

Erstellt: 03/2013| Geändert: 10/2015

Eclipse

Das Erzeugen geht auch in Eclipse als Builder:

Dann noch den Pfad anpassen:

Beim Build wird dann die Dokumentation gerendert.

Erstellt: 07/2013| Geändert: 10/2015

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.

Erstellt: 03/2013| Geändert: 10/2015

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).

Erstellt: 09/2010| Geändert: 10/2015

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.

Erstellt: 09/2010| Geändert: 10/2015

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

Erstellt: 09/2010| Geändert: 10/2015