Transition to PHP-Based reStructuredText Rendering for TYPO3 Documentation

Another key feature of the new system is its simplicity in linking. Each headline in the documentation automatically generates a reference, making it easier to share and navigate specific sections. For example, linking to a specific section is as straightforward as copying the provided permalink or using a reST reference.

The migration path from Sphinx to the new PHP-based rendering is designed to be simple. Projects that include a Documentation/guides.xml file will automatically switch to the new rendering system. Additionally, a Docker-based migration tool is available to help convert Sphinx settings (Documentation/Settings.cfg) to the new format.

Handling Permanent Anchors

In case no permanent anchor has been assigned to the headline, a warning will be displayed to avoid potential cross-linking issues in the future. This warning helps ensure that links remain stable even if there are slight changes to headlines or their locations.

For more details, refer to the Links & Cross References chapter.

Advantages of the New Rendering

The transition to PHP-based rendering brings numerous benefits:

• Speed: The new system renders documentation significantly faster, enhancing productivity and allowing for near real-time updates
• Ease of Linking: Automatic generation of references for each headline simplifies navigation and sharing of specific documentation sections.
• Simple Migration: The migration process is streamlined with tools to facilitate the conversion from Sphinx to the new PHP-based system.
• Local Rendering: Documentation can now be rendered locally using Docker or Podman, providing flexibility for developers.

TYPO3 Contribution Bootup Day

Introduction to the Contribution Bootup Day

The TYPO3 Contribution Day, scheduled for 31 July 2024, is a special event designed to introduce you and your developers to the world of TYPO3 contributions. This Documentation Edition of the Bootup Day is a perfect opportunity to learn how you can give back to the TYPO3 community, understand the ecosystem, and find out where your contributions will be most valuable.

Supporting Extension Authors

During the Bootup Day, the TYPO3 Documentation Team will offer support to extension authors in updating their documentation to the new PHP-based rendering system. Whether you need help migrating existing documentation or creating new documentation using the new rendering engine, our team will be there to guide you through the process. This hands-on support ensures that your documentation is up-to-date and leverages the latest tools and features available.

Contributing to the Documentation Team

If you are interested in contributing to the TYPO3 Documentation Team, the Bootup Day is an excellent starting point. The workshop, led by Lina Wolf and the TYPO3 Documentation Team, will prepare you for active contribution. You’ll gain insights into the documentation process, learn best practices, and understand how to effectively collaborate with the team. This preparation is particularly useful for those planning to participate in the TYPO3 Developer Days Coding Night, which is one day after the TYPO3 Contribution Bootup Day at the same location.

Event Details

Date and Time: 31 July 2024, from 13:00 to 17:00
Location: GenoHotel, Am Rüppurrer Schloss 40, 76199 Karlsruhe 

More Information

Please note that food and beverages are not included in the participant ticket.

User Experiences

Jaap van Otterdijk, the maintainer of phpDocumentor, emphasized the collaborative nature of this project:

“The new documentation rendering tool of TYPO3 is the result of months of work and collaboration between different open source projects. The underlying code base can be used in many other projects without being forced to use a certain framework or application. For me, this is what open source is about, working together building a project that serves everyone in their own way. By building bridges between different groups in the PHP Community, we will be able to deliver more powerful tools and libraries, which is a great win for everyone using PHP.”

Georg Ringer highlighted the seamless migration experience:

“Thanks a lot to the Documentation Team who took care about the complete migration, including a CI testing pipeline. They migrated not only the documentation of EXT:news but also e.g EXT:tt_address. I didn’t need to take care about anything and whenever I have troubles or questions they not only give quick answers but also create pull requests to minimize the effort on the side of the extension developers. This is why I love open source and the TYPO3 community.”

Benni Mack praised the new system’s collaborative capabilities:

“The new documentation rendering engine finally allows every TYPO3 contributor to write documentation in almost real-time, enjoying an almost What-You-See-Is-What-You-Get Engine based on ReST. What an amazing collaborative effort, that will pay off and is a fantastic base for the coming years!”

Simon Preatorius also expressed his satisfaction with the new system’s ease of use:

“I was very impressed by how easy it was to switch the Fluid documentation to the new Rendering. Cheers to the documentation team for this great effort to make the documentation tooling so much easier to use.”

A Significant Advancement for TYPO3 Documentation 

The transition to the PHP-based restructured Text rendering system marks a significant advancement for TYPO3 documentation. This new system not only improves rendering speed and ease of use but also enhances the overall experience for contributors. With these improvements, the TYPO3 Documentation Team is confident that this new rendering engine will greatly benefit the TYPO3 community, providing a robust foundation for the future.