TYPO3 Dokumentation mit ReStructuredText

24
TYPO3 Dokumentation mit reS tructured T ext Einführung und Überblick

description

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

Transcript of TYPO3 Dokumentation mit ReStructuredText

Page 1: TYPO3 Dokumentation mit ReStructuredText

TYPO3 Dokumentationmit reStructuredTextEinführung und Überblick

Page 2: TYPO3 Dokumentation mit ReStructuredText

www.typo3-lisardo.deTYPO3 Dokumentation mit reST

Über mich 2

Peter Linzenkirchner

Lisardo EDV-Beratung, Augsburg

Freelancer: TYPO3, HTML, CSS

TYPO3 Certified Integrator

Web: www.typo3-lisardo.de

Page 3: TYPO3 Dokumentation mit ReStructuredText

www.typo3-lisardo.deTYPO3 Dokumentation mit reST

Dokumentation mit Openoffice 3

Page 4: TYPO3 Dokumentation mit ReStructuredText

TYPO3 CMS Doku auf docs.typo3.org 4

Page 5: TYPO3 Dokumentation mit ReStructuredText

Extension Dokumentation 5

Page 6: TYPO3 Dokumentation mit ReStructuredText

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/ReSThttp://de.wikipedia.org/wiki/ReStructuredText

Page 7: TYPO3 Dokumentation mit ReStructuredText

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 Liste2) 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 FalseTrue 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

Page 8: TYPO3 Dokumentation mit ReStructuredText

www.typo3-lisardo.deTYPO3 Dokumentation mit reST

reStructuredText: HTML 8

Page 9: TYPO3 Dokumentation mit ReStructuredText

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«

Page 10: TYPO3 Dokumentation mit ReStructuredText

www.typo3-lisardo.deTYPO3 Dokumentation mit reST

reStructuredText – TestenOnline-EditorenMit 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-EditorenUm 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

Page 11: TYPO3 Dokumentation mit ReStructuredText

www.typo3-lisardo.deTYPO3 Dokumentation mit reST

InstallationGlobal, ausserhalb von TYPO3Damit 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

Page 12: TYPO3 Dokumentation mit ReStructuredText

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

Default Template

Page 13: TYPO3 Dokumentation mit ReStructuredText

www.typo3-lisardo.deTYPO3 Dokumentation mit reST

Installation in TYPO3 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 ConsoleDamit können innerhalb von fileadmin reST-Projekte angelegt werden

Sphinx Documentation LibraryDamit können die reST-Dokumentationen von Betrachtet und Bearbeitet werden.

Page 14: TYPO3 Dokumentation mit ReStructuredText

www.typo3-lisardo.deTYPO3 Dokumentation mit reST

Sphinx Console – Projekt anlegen 14

Page 15: TYPO3 Dokumentation mit ReStructuredText

www.typo3-lisardo.deTYPO3 Dokumentation mit reST

Sphinx Console – Index.rst 15

Page 16: TYPO3 Dokumentation mit ReStructuredText

www.typo3-lisardo.deTYPO3 Dokumentation mit reST

Sphinx Console – Settings.yml 16

Page 17: TYPO3 Dokumentation mit ReStructuredText

Sphinx Console – HTML generieren 17

Page 18: TYPO3 Dokumentation mit ReStructuredText

Sphinx Console – HTML 18

Page 19: TYPO3 Dokumentation mit ReStructuredText

www.typo3-lisardo.deTYPO3 Dokumentation mit reST

Sphinx Console – Dateistruktur 19

Page 20: TYPO3 Dokumentation mit ReStructuredText

www.typo3-lisardo.deTYPO3 Dokumentation mit reST

Sphinx Documention – Kickstarter 20

In Extensions können hier neue Dokumentationen angelegt und/oder vorhandene Openoffice-Dokument in reST-Dokumentationen konvertiert werden.

Page 21: TYPO3 Dokumentation mit ReStructuredText

reST-Dokumentationen anschauen 21

Page 23: TYPO3 Dokumentation mit ReStructuredText

reST-Dokumentation bearbeiten 23

Page 24: TYPO3 Dokumentation mit ReStructuredText

www.typo3-lisardo.deTYPO3 Dokumentation mit reST

reST-Dokumentationen für Extensions 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.