Documentation rendering with phpDocumentor/guides

Restructured Text (or reST) is a helpful format for writing documentation. In a joint-effort developers from several large PHP project have been working together to develop a new, PHP-based reST parser and renderer called the “Guides” by phpDocumentor, composer-key `phpdocumentor/guides < https://github.com/phpDocumentor/guides`.>
The advantages of reST (and other markup languages) over binary formats such as Open Office or Word are: The documentation can be kept under version control. It is stored in a human-readable form and not dependent on any proprietary software and it can be auto-generated in parts.
The steps of parsing reST and rendering the output (for example HTML or LaTEX) are completely separated. The reST parser transforms the markup into an Abstract Syntax Tree (AST). The tree is modified by a compiler and then transferred to the renderer, which turns it into HTML or another desired output format. Both the parser and the renderer are exchangeable. This way it is also possible to interpret any input format. We used MarkDown (md) as a proof of concept, this would need more work, however.
The HTML output format comes with easy templating. The guides deliver a plain template to be used in web components, and a simple bootstrap-based ready to use template. Further templates can be installed as Symfony extensions via composer. I will demonstrate a template for the official TYPO3 documentation and a custom template styled in the CI of the company I am working for. We use the custom template for individual project documentation, such as technical documentation and editor documentation.
You can install our demo-project with a custom example template and the standard TYPO3 Template to try out the parsing and rendering for yourself: https://github.com/TYPO3-Documentation/rst-rendering-demo

The expectations for documentations are growing. A new extension without documentation is unusable for most user in the increasingly complex software world. Many customers expect to receive technical documentation and or an individual editor’s manual for their web project.
The large PHP projects Symfony, Doctrine, phpDocumentor and TYPO3 have joint effort to improve writing and rendering documentation.

Using a Markup language like restructured Text (reST) to write Documentation has a lot of benefits. Rendering and theming reST with a Phython-based Tool like Sphinx feels strange to PHP developers and they cannot fix issues easily.
PHP developers from 4 large PHP projects joint forces to solve this Problem and create the PHP-based reST parser and renderer phpdocumentor/guides (formerly doctrine/rstparser).
Learn how you can use reST rendered by the Guides to write modern and easy to maintain documentation for your projects and extensions. I will demonstrate how you can use the TYPO3 standard theme or how you can write your own theme.