Fluid ViewHelper reference generation 

What is taken from the PHP sources 

The generator reads the ViewHelper classes of the TYPO3 Core and of the package Fluid Rendering Engine. From each class it takes the phpDoc-style comment above the class and the arguments registered in its initializeArguments() method.

Only that short description and the argument list come from PHP. Everything else on a ViewHelper page — the explanations, the examples and the page structure — is written by hand in the reference repository, and that is where it should stay. See Hand-written documentation is preferred.

Fixing a wrong or missing short description is therefore a change to the PHP doc-comment, and follows the TYPO3 Contribution Guide - Core Development. Adding an example is a change to the manual, through a pull request against the reference repository.

Generation of the reStructuredText files and JSON files 

The Fluid ViewHelper Documentation Generator produces, for each documented Fluid namespace, a directory of rST files and one JSON file.

The namespaces are configured in JSON files in the generator repository, below config/. A configuration may combine several namespaces into one — this is how f:* in TYPO3 ends up covering both the ViewHelpers of EXT:fluid and those of Fluid Standalone.

Rendering the ViewHelper reference to HTML 

The generated files are copied into TYPO3CMS-Reference-ViewHelper by the GitHub action, under two different rules:

reStructuredText files

Copied only if no file of that name exists yet. An existing page is never overwritten, so hand-written content is safe. A ViewHelper that is removed from the Core keeps its page until somebody deletes it by hand.

JSON files

Always overwritten. This is what keeps descriptions and argument tables current: the typo3:viewhelper directive on a page reads the JSON at render time, so a changed doc-comment reaches the published page without the page itself being touched.

Documentation/Index.rst is explicitly restored after the copy and is maintained by hand, as are the guides.xml and everything else outside the generated namespace directories. TYPO3CMS-Reference-ViewHelper is then rendered by the standard rendering process.

GitHub action "Fluid ViewHelper documentation" 

All of the above is combined into the workflow .github/workflows/fluid-viewhelper.yml in the repository t3docs-ci-deploy. It runs once a day and can also be started manually through the GitHub UI by the TYPO3 Documentation team.

The workflow runs once per documented TYPO3 version. Each run installs a slim TYPO3 setup for that version, defined in Build/fluid-viewhelpers/<version>/composer.json, and pushes its result to the branch of the same name in the reference repository. Adding a version therefore means adding both the directory and an entry in the workflow's matrix, which also pins the PHP version that version of TYPO3 needs.

The resulting commits are titled [BOT][TASK] Only add new ViewHelper documentation files. There are none on days when no ViewHelper was added and no description changed.

Maintainers need to occasionally watch for failed or stuck workflow runs, because the pipeline can stop without anything looking wrong:

• GitHub disables a scheduled workflow after 60 days without a commit to its repository. The daily runs then simply stop, and there is no failed run to notice. Re-enable the workflow on the Actions tab, or start it once manually, and the schedule resumes.
• The step that writes to the reference repository is marked continue-on-error, so a failure there does not turn the run red.

In both cases the symptom is the same: the reference stops receiving commits while every run still looks fine.