diff --git a/Documentation/Maintainers/FluidViewHelper.rst b/Documentation/Maintainers/FluidViewHelper.rst new file mode 100644 index 00000000..399dabe1 --- /dev/null +++ b/Documentation/Maintainers/FluidViewHelper.rst @@ -0,0 +1,102 @@ +.. include:: /Includes.rst.txt +.. _fluid-viewhelper-reference-generation: + +===================================== +Fluid ViewHelper reference generation +===================================== + +The :ref:`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 +:ref:`TYPO3 Contribution Guide - Core Development `. + + +.. _fluid-viewhelper-reference-generation-schema: + +The Fluid ViewHelper schema generator +===================================== + +The PHP files defining the ViewHelpers are transferred into :file:`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 +:file:`schema.xsd`, adjustments need to be made in the PHP files. :file:`schema.xsd` files are considered "read-only" due to their auto-generated nature. The information from the +:file:`schema.xsd` files can, if configured through plugins, also used by IDEs for context sensitive help in +editors etc. + +You can generate the :file:`schema.xsd` files yourself for local testing, like this: + +.. code-block:: bash + + 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`). + +.. _fluid-viewhelper-reference-generation-rst: + +Generation of the reStructuredText files +========================================= + +The :abbr:`rst (reStructuredText)` files get generated from the +:file:`schema.xsd` files (See section +:ref:`fluid-viewhelper-reference-generation-schema`) with the help of the +following tool: +`Fluid ViewHelper Documentation Generator `. + +Please note that the TYPO3 Core initially uses `reStructuredText` formatting +inside the phpDoc comments already, and this is passed on to the :file:`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 :file:`.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 :file:`schema.xsd` files but +not the generated standalone :file:`.rst` files, a bug in that generator may exist and needs adressing. + +.. _fluid-viewhelper-reference-generation-html: + +Rendering the ViewHelper reference to HTML +========================================== + +The :abbr:`rst (reStructuredText)` files generated in step +:ref:`fluid-viewhelper-reference-generation-rst` will be saved by the +:ref:`GitHub action ` into +the repository `Fluid ViewHelper Reference `. + +In this repository all files not overridden by the +`Fluid ViewHelper Documentation Generator ` +are maintained, Including the start page :file:`Index.rst` and the +:ref:`guides.xml `. This repository is then rendered by +the standard rendering process. + +.. _fluid-viewhelper-reference-generation-github-action: + +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 `__. diff --git a/Documentation/Maintainers/Index.rst b/Documentation/Maintainers/Index.rst index c74ed70d..137624cf 100644 --- a/Documentation/Maintainers/Index.rst +++ b/Documentation/Maintainers/Index.rst @@ -10,6 +10,7 @@ For maintainers :maxdepth: 1 BackportChanges + FluidViewHelper Changelog NewMajorCoreVersion Tools