- Documentation is now using the Sphinx Documentation Tool and 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
docs.typo3.orgWe have set up a preliminary documentation server which is now online at http://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 http://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.