Einführung und Überblick, TYPO3camp München 2013

1. TYPO3 Dokumentation
mitreStructuredText
Einführung und Überblick

2. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
Übermich 2
Peter Linzenkirchner
Lisardo EDV-Beratung, Augsburg
Freelancer: TYPO3, HTML, CSS
TYPO3 Certified Integrator
Web: www.typo3-lisardo.de

3. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
DokumentationmitOpenoffice 3

4. TYPO3CMSDokuaufdocs.typo3.org 4

5. ExtensionDokumentation 5

6. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
reStructuredText 6
reStructuredText ist eine Auszeichnungssprache ähnlich markdown oder
textile. Sie wurde entwickelt für die Dokumentation der Programmiersprache
Python, die für den Parser auch benötigt wird.
Vorteile
auch ungeparst einigermaßen gut lesbar ist
textbasiert
kann mit Git oder SVN versioniert werden
speziell für Dokumentation entwickelt
Export in andere Formate: ODT, Manpage, HTML, XML, LaTeX, PDF etc.
http://wiki.typo3.org/ReST
http://de.wikipedia.org/wiki/ReStructuredText

7. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
Abschnitt-Titel (Section)
=========================
Unterabschnitt
--------------
Normaler Text und so weiter und so fort.
- Erster Punkt
- Zweiter Punkt
- Dritter Punkt
1) Ein Punkt einer nummerierten Liste
2) Zweites...
3) Dritter Punkt der nummerierten Liste
- der Text hier wird kursiv: *text*
- der hier wird fett: **text**
- und das ist Code: ``text``
===== ===== =======
A B A and B
===== ===== =======
False False False
True True True
===== ===== =======
reStructuredText–Syntax 7
Manuals: http://docutils.sourceforge.net/rst.html
http://wiki.typo3.org/ReST_Syntax
Dieser Absatz bekommt eine Fußnote. [1]_
Bilder
------
.. image:: images/myimage.jpg
:height: 299
:width: 348
:scale: 50
:alt: Katze beim Duschen
Hyperlinks
----------
_reStructuredText: http://docutils.sf.net/rst.html
Links auf die Dokumentation von TYPO3:
---------------------------------------
- :ref:`TYPO3 Tutorial for Editors <t3editors:start>`
- :ref:`Getting Started Tutorial <t3start:start>`
Fußnoten
---------
.. [1] Eine Fußnote

8. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
reStructuredText:HTML 8

9. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
reStructuredText–Voraussetzungen 9
Die Markup-Sprache muss geparst und in eine
andere Sprache konvertiert werden.
Voraussetzungen:
Python
Sphinx – das Tool, das die Umwandlung in HTML vornimmt
die Templates von TYPO3
Tools zum Erstellen von PDFs (optional)
Zwei mögliche Arbeitsweisen:
global: Installation der Tools auf dem Rechner
innerhalb von TYPO3 mit der Extensions »sphinx«

10. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
reStructuredText–Testen
Online-Editoren
Mit Online-Editoren kann man reStructuredText ausprobieren, ohne vorher
alle Komponenten installieren zu müssen. Allerdings ist es nicht möglich für
den Export die TYPO3-Templates zu verwenden.
https://notex.ch
Umfangreicher Editor, mit einem kompletten Beispielprojekt und
verschiedenen Exportmöglichkeiten: HTML, PDF, EPUB
http://rst.ninjs.org
Simpler Editor, der mit Hilfe von zwei Themes reStructured Text in HTML
umwandelt.
Offline-Editoren
Um diese benutzen zu können, müssen vorher die Komponenten alle
installiert werden. Eine Liste von Offline-Editoren findet sich hier:
http://wiki.typo3.org/Editors_(reST)
10

11. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
Installation
Global, ausserhalb von TYPO3
Damit können reST-Dokumentation auch ausserhalb von TYPO3 erstellt
werden, und auch mit anderen Templates als TYPO3. Installation und weitere
Arbeit sind aber etwas umständlicher als innerhalb von TYPO3.
Am besten einfach den Anleitungen im Wiki folgen:
Mac + Linux: http://wiki.typo3.org/Rendering_reST_on_Linux
Windows: http://wiki.typo3.org/Rendering_reST_on_Windows
Die Anleitungen sind durchdacht und haben bei mir problemlos funktioniert.
Ausführliche Dokumentation zu Sphinx:
http://sphinx-doc.org
11

12. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
12
Das default-Theme ist
das Standardtheme der
Python-Dokumentation.
Weitere Themes, Installations-
anleitungen und Anleitung
zum Erstellen eigener Themes
sind auf der Sphinx-Webseite
zu finden:
http://sphinx-doc.org/theming.html
DefaultTemplate

13. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
InstallationinTYPO3 13
Extension »sphinx«
http://typo3.org/extensions/repository/view/sphinx
Diese Extension installiert die nötigen Tools (Python, Sphinx und die TYPO3-
Templates) in die TYPO3-Installation.
Installation erfolgt in zwei Schritten: Download und Installation der Extension,
danach im Extensions Manager über die Updatefunktion die Tools
herunterladen. Der Vorgang ist in der Dokumentation gut erklärt.
Ausserdem installiert es zwei Module, die bei der Arbeit mit
Dokumentationen hilfreich sind:
Sphinx Console
Damit können innerhalb von fileadmin reST-Projekte angelegt werden
Sphinx Documentation Library
Damit können die reST-Dokumentationen von Betrachtet und Bearbeitet
werden.

14. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
SphinxConsole–Projektanlegen 14

15. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
SphinxConsole–Index.rst 15

16. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
SphinxConsole–Settings.yml 16

17. SphinxConsole–HTMLgenerieren 17

18. SphinxConsole–HTML 18

19. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
SphinxConsole–Dateistruktur 19

20. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
SphinxDocumention–Kickstarter 20
In Extensions können hier neue Dokumentationen angelegt und/oder
vorhandene Openoffice-Dokument in reST-Dokumentationen konvertiert
werden.

21. reST-Dokumentationenanschauen 21

22. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
Lokalisierung 22
http://wiki.typo3.org/Localization_(reST)
http://docs.typo3.org/typo3cms/extensions/sphinx/latest/UsersManual/
DocsTypo3Org/Index.html

23. reST-Dokumentationbearbeiten 23

24. www.typo3-lisardo.deTYPO3 Dokumentation mit reST
reST-DokumentationenfürExtensions 24
Manual / Anleitung
http://wiki.typo3.org/ReST_for_extension_manuals
http://docs.typo3.org/typo3cms/extensions/sphinx/latest/Index.html
Die aktuellen Extensions sollen dann unter dieser URL erscheinen:
http://docs.typo3.org/typo3cms/extensions/myext/latest/Index.html
Aktuelle Einschränkungen
die Dokumentation erscheint noch nicht im TER
die Dokumentation muss manuell von Documentation-Team freigeschaltet
werden. Passiert das nicht, wird unter der URL nur das konvertierte
Openoffice-Dokument gezeigt.
Diese Einschränkungen sollen demnächst wegfallen.