On 20 and 21 April 2023, members of at least four open-source projects will meet at the TYPO3 office in Düsseldorf, Germany, to bring PHP-based reStructuredText parsing forward.
The TYPO3 Core Documentation (References, Changelog, Guides, etc.), as well as the Documentation of many TYPO3 Extensions, is based on reStructuredText (reST) for more than ten years.
Moving from Python to PHP and Joining Forces
However the parsing and rendering of reST is still done in the Python-based tool Sphinx in the world of TYPO3 Documentation. This has several shortcomings: We are notoriously short on Python developers while we do have an abundance of PHP developers, being PHP based ourselves. The rendering has become slower and slower with the years, as our rendering pipeline has historically grown. It needs a makeover.
Both Symfony and Doctrine also base their documentation on reST. They face similar challenges, like management of changes across versions, documentation for third-party packages, etc.
At the Symfony conference in Paris in October 2022, Ryan Weaver and Lina Wolf got the idea to kickstart a closer cooperation on documentation infrastructure topics. Their documentation is currently based on the doctrine/rst-parser package. Unfortunately there has not been much contribution to their reST parser in the past years.
“The world of documentors can be a lonely one! Being able to meet another team from a similar technology and compare strategies for code blocks, examples and maintenance is priceless.”
—Ryan Weaver, Symfony
Merging the Fork
The phpDocumentor project are the ones who set the standard for PHPDoc documentation (starting with /**) that we are using in TYPO3. In 2020, they started working on a fork of the doctrine/rst-parser, and the two projects diverged.
The phpDocumentor reST-parser is integrated into the complete phpDocumentor project that also renders API information for PHP. It can also be run standalone, but it is still in the experimental stage.
Now we want to bring everyone back together and work on a new and better version together.
“Documentation is crucial for building maintainable code, and we're trying to set a new standard with phpDocumentor's reST parser. Collaborating with other maintainers to learn about tooling requirements is an invaluable opportunity that I couldn't have imagined. I am excited to see how this open-source collaboration will shape the future of PHP documentation.”
—Jaap van Otterdijk, phpDocumentor
Join a Sprint With phpDocumentor, Doctrine, Symfony, and TYPO3
On 20 and 21 April 2023, members of the TYPO3, phpDocumentor, Doctrine and Symfony documentation teams will meet in Düsseldorf. They will work on a new, stable version of the reST parser and renderer that integrates both forks.
“One of the major benefits of true Open Source projects is the collaboration between projects, making better software and tools while getting to know new like-minded people. It's truly a special experience I can highly recommend.”
—Benni Mack, TYPO3 Core Team Lead
If you are interested in joining the code sprint or the development in general, talk to Lina Wolf @linawolf or the #typo3-documentation channel in the TYPO3 Slack. You can also find Lina in the Doctrine, Symfony and phpDocumentor Slack. You can also write an email to lina.wolf(at)typo3.org.
Sprint participants must register with Lina Wolf no later than Wednesday 12 April 2023. The TYPO3 Documentation Team books hotel and covers travel costs, lodging, and food for registered participants during the sprint according to the TYPO3 travel reimbursement regulations.
