The Documentation Team in 2012

• Documentation is now using the <link http: sphinx-doc.org>Sphinx Documentation Tool and <link http: docutils.sourceforge.net>Docutil's ReStructuredText format (ReST) as markup.
• All official manuals are migrated from OpenOffice format to ReST
• Documentation is expected to be in a sub-folder "./Documentation" of a given project.
• The final structure of the rendered documentation reflects the structure and naming of files found in "./Documentation"

At the typo3.org code sprint by Martin Bless The documentation team created extensions for the Sphinx Documentation Tool to make it meet the specific needs of the TYPO3 community:

• added the possibility to configure Sphinx via Yaml,
• created a Sphinx extension that offers an easy way to write tables in ReST,
• created an extension that lists all the available cross-reference targets to the reader,

• added a builder "t3html" that produces html pages specially tailored for TYPO3

A <link http: git.typo3.org documentation resttools.git tree head: extendingsphinxfortypo3>"t3sphinx" package is provided that makes these extensions available to all documentation writers who want to do the rendering of documentation on their own machine. Symbolic cross-referencing is now reality: you can point to any target in the documentation by using a symbolic name. This means that you don't need to know anything about the true target URL. Official manuals now are normal Git projects with ReST code on our <link http: git.typo3.org>Git server. The manuals are open for contributions via the usual Git/Gerrit review workflow like any other TYPO3 project. This possibility is new and not well-known yet. All developers are encouraged to provide documentation snippets directly by pushing to Gerrit instead of leaving notes in the bugtracker. A full contributing manual will be made available soon. A good participation platform is essential for providing good documentation. Early this year a cron job was created that regularly checks the TER for extensions with an OpenOffice document "manual.sxw". All sxw docs are transformed to ReST and rendered as HTML again on <link http: docs.typo3.org typo3cms extensions>docs.typo3.org/typo3cms/extensions/ Bundling this knowledge a package "<link http: git.typo3.org documentation resttools.git tree head: t3pythondocbuilderpackage>T3PythonDocBuilder" has been compiled that's available from the Git server too. You can run that application on your machine with just two parameters: path to a manual.sxw and path to a temp folder. It will then do all transformations necessary automatically to migrate from an OpenOffice file to the ReST documentation for TYPO3. As far as we know there is no such tool anywhere else in the world. All documentation updates for TYPO3 CMS 6.0 are already available as ReST documents.

docs.typo3.org

We have set up a preliminary documentation server which is now online at <link http: docs.typo3.org>docs.typo3.org.
Currently the docs server is set-up manually and it works half manually. New TER manuals are rendered automatically every two hours. The official documents have a fixed location (=URL). Editors can click a link in the browser to trigger new rendering of the current documentation master, which will be executed within the next five minutes.

Virtual machine and Flow

• provide a chef/vagrant set-up that will set-up a complete docs server. It's planned to have that on a virtual machine,
• use Flow to provide a service "GetTheDocs" on the documentation server. It has kind of a client server architecture. It offers the things we now can do with our documentation as a service: Take an OO manual.sxw file and return the ReST documentation project. Or take a ReST documentation project and return the HTML or PDF files and so on.
• So this Flow application knows about actions someone would like to do and knows how to address the Sphinx Documentation Tools to get those jobs done. As a result people can use the features we've build without having to do complicated set-ups on a private machine.

During the code sprint

• Fabien Udriot and me have been sitting side by side for the first time working on several tasks. This close cooperation allows for quick identification of problems. The "GetTheDocs" application is running now! Only a web interface (form, explanation) is missing. That will be added to <link http: docs.typo3.org>docs.typo3.org
• Fabien is working on a Flow application that will manage all the actions of the documentation server. It accepts rendering tasks and adds them to a task queue. The task queue is being serviced independently and asynchronously by another task. The Flow application does housekeeping and maintains database tables of scheduled tasks and the available rendered documents. This will provide services for listing, search and so on. Good progress on this was made during the code sprint.
• In parallel with the 6.0 release we went online with docs.typo3.org. docs.typo3.org sports a new layout of Sphinx (theme "t3org") complying with the overall typo3.org theme. Some landing pages and a temporary menu structure were also integrated. The look and feel of docs.typo3.org is still preliminary. There are quite some design changes that still need to be done and there are tons of features that will be integrated in the future, like PDF generation.