Create a public reStructuredText API for the TYPO3 Core

Application by
Lina Wolf

What is your idea about?
Currently developers wishing to access information on the Core PHP API have the choice of using https://api.typo3.org/, GitHub - TYPO3/typo3: The TYPO3 Core - Enterprise Content Management System. Synchronized mirror of https://review.typo3.org/Packages/TYPO3.CMS or looking directly into the code. Each of these methods show the complete code structure to the user, including protected, private and @internal members. The latter two even show the complete code. This tempts extension / sitepackage developers to rely on non-public API and implementation details.

When writing documentation the contributors tend to mention PHP classes and methods without linking them and sometimes without verifying that they exist. Often only the name of the class is mentioned without reference to the namespace. This causes confusion. When classes are deprecated or removed they have to be found manually in the documentation.

We do have a great syntax to document PHP in rst already:

https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/WritingReST/Phpdomain.html

And the automatic screenshot tool can be extended to create this syntax automatically from PHPdoc comments and PHP structure (such as return types, variable types, modifiers etc)

We do have a first proof of concept in the screenshot tool that would need to be extended:

And we already generate the public API for all Core events with it:
https://docs.typo3.org/m/typo3/reference-coreapi/11.5/en-us/ApiOverview/Hooks/Events/Recordlist/ModifyRecordListTableActionsEvent.html

This has already improved the time and effort needed to document new Events and update existing ones. Also it is very easy to link to events from within the documentation.

We want to upscale these efforts to create a PHP domain of the complete public API. Wherever Core classes, interfaces, methods, constants etc are mentioned in the documentation they can then be easely linked.

When a linked Class or method is deprecated, internalized or removed in the current version, the linking will break and the rendering will cause a warning that then someone from the documentation team can take care of.

The same technique can then be used by authors of third party extensions who also offer public PHP API

What is the potential impact of your idea?
TYPO3 has a very steep learing curve for new developers. Seeing internal API or even code unfiltered while trying to find public API is very distracting for newbies and even experienced developers.

This can lead to developers circumventing the public API or using internal API. This makes updates of TYPO3 projects and extenisions much harder.

Much critique of why agencies dont want to use TYPO3 is the steep learning curve for developers (or not finding a developer), and that TYPO3 projects are expensive to create and keep up to date.

We want to improve this situation by making the public API easier to access and understand, without confusing developers with details that they should not rely on.

By making development of TYPO3 projects, sitepackages and extensions easier we want to attract more people to the TYPO3 project

Who can / should implement your idea?
I will take care myself

Approximate Funds needed
€10,000 - €25,000

2 Likes