Fluid ViewHelper reference generation

The Fluid ViewHelper Reference gets automatically updated by changes to the according ViewHelper classes in the TYPO3 Core and the package Fluid Rendering Engine.

The generated documentation specifically depends on the phpDoc-style inline comments on top of the ViewHelper classes as well as the configured arguments in their php:initializeArguments() method.

Changes in wording or arguments thus need to be made inside the relevant files of these two repositories. For contributions to the TYPO3 Core, follow the TYPO3 Contribution Guide - Core Development.

The Fluid ViewHelper schema generator

The PHP files defining the ViewHelpers are transferred into schema.xsd files. The package fluid-schema-generator is responsible for this step, automatically executed via triggered GitHub actions. If information is missing in the schema.xsd, adjustments need to be made in the PHP files. schema.xsd files are considered "read-only" due to their auto-generated nature. The information from the schema.xsd files can, if configured through plugins, also used by IDEs for context sensitive help in editors etc.

You can generate the schema.xsd files yourself for local testing, like this:

git clone git@github.com:typo3/typo3.git core
cd core
composer require -o -n --no-progress typo3/fluid-schema-generator
mkdir -p ../schemas/typo3fluid/fluid/latest
./bin/generateschema TYPO3Fluid\\\Fluid > ../schemas/typo3fluid/fluid/latest/schema.xsd
mkdir -p ../schemas/typo3/core/latest
./bin/generateschema TYPO3\\\CMS\\\Core > ../schemas/typo3/core/latest/schema.xsd
mkdir -p ../schemas/typo3/fluid/latest
./bin/generateschema TYPO3\\\CMS\\\Fluid > ../schemas/typo3/fluid/latest/schema.xsd
mkdir -p ../schemas/typo3/backend/latest
./bin/generateschema TYPO3\\\CMS\\\Backend > ../schemas/typo3/backend/latest/schema.xsd

The composer step will automatically require the Fluid Rendering Engine in the version used by the Core version you fetched via GIT (by default, main).

Generation of the reStructuredText files

The rst files get generated from the schema.xsd files (See section The Fluid ViewHelper schema generator) with the help of the following tool: Fluid ViewHelper Documentation Generator <https://github.com/TYPO3-Documentation/fluid-documentation-generator>.

Please note that the TYPO3 Core initially uses reStructuredText formatting inside the phpDoc comments already, and this is passed on to the schema.xsd files with exactly that formatting. IDEs may want to interpret these schemas with expected HTML or MarkDown syntax, so you may see raw reStructuredText output in this case. The generated Documentation for docs.typo3.org takes care of transforming the generated .rst files to HTML, by utilizing the https://github.com/TYPO3-Documentation/render-guides project.

If any of the ViewHelper source code documentation is only contained in the schema.xsd files but not the generated standalone .rst files, a bug in that generator may exist and needs adressing.

Rendering the ViewHelper reference to HTML

The rst files generated in step Generation of the reStructuredText files will be saved by the GitHub action into the repository Fluid ViewHelper Reference <https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-ViewHelper>.

In this repository all files not overridden by the Fluid ViewHelper Documentation Generator <https://github.com/TYPO3-Documentation/fluid-documentation-generator> are maintained, Including the start page Index.rst and the guides.xml. This repository is then rendered by the standard rendering process.

GitHub action "Fluid ViewHelper Documentation"

All processes described above are combined for automatic execution as a GitHub action in the repository t3docs-ci-deploy. It is triggered automatically once a day, or can be executed manually through the GitHub UI by the TYPO3 Documentation team.

Maintainers needs to occasionally watch for failed or stuck Workflow runs.