t3docs/fluid-documentation-generator

Generates automatic documentation in RST format based on Fluid ViewHelper source files

4.4.0 2024-09-16 04:30 UTC

Requires

• php: ^8.2
• ext-json: *
• justinrainbow/json-schema: ^5.2
• typo3fluid/fluid: ^2.12 || ^4.0 || dev-main

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.59.3
• phpstan/phpstan: ^1.11.5
• phpstan/phpstan-phpunit: ^1.4.0
• phpunit/phpunit: ^11.2.5

LGPL-3.0-or-later

README

This package generates an automatic Fluid ViewHelper reference documentation in RST format. The included CLI command is configured with json files. Based on this configuration, the following assets are generated:

• a directory structure with RST files to navigate between namespaces, groups of ViewHelper as well as the ViewHelpers themselves
• a json file which contains all relevant information about the Fluid namespace and its ViewHelpers

The result can be rendered with render-guides, which contains a special RST directive to interpret the generated JSON file.

Installation

This package needs to be installed inside a composer project that contains all ViewHelpers that should be documented.

composer req --dev t3docs/fluid-documentation-generator

Configuration and Usage

The documentation assets will be generated by using the following CLI command:

vendor/bin/fluidDocumentation generate viewhelpers1_config.json viewhelpers2_config.json ...

You can specify 1-n config files, separated by a space character. If you specify multiple files, their order is important because it will determine the order on the documentation's index page. You can use wildcards as well, see examples below.

Each configuration file must respect the provided JSON schema. A minimal configuration file could look like this:

{
    "name": "MyPackage",
    "namespaceAlias": "my",
    "targetNamespace": "http://typo3.org/ns/Vendor/MyPackage/ViewHelpers"
}

The resulting JSON file will contain all ViewHelpers in the PHP namespace Vendor\MyPackage\ViewHelpers. The result will be placed in a folder called fluidDocumentationOutput. The output folder can be changed by providing the environment variable FLUID_DOCUMENTATION_OUTPUT_DIR. In the example, the folder structure will look like this:

• fluidDocumentationOutput/
  • MyPackage/
    • Index.rst
    • MyViewHelper.rst
    • ...
  • Index.rst
  • MyPackage.json

Examples

Generate ViewHelper reference for dev-main of TYPO3 Core with config files:

git clone [e-mail]:TYPO3/typo3.git
composer install
composer require --dev t3docs/fluid-documentation-generator
composer exec fluidDocumentation generate vendor/t3docs/fluid-documentation-generator/config/typo3/*

Generate ViewHelper reference for dev-main of Fluid Standalone with config files:

git clone [e-mail]:TYPO3/Fluid.git
composer install
composer require --dev t3docs/fluid-documentation-generator
composer exec fluidDocumentation generate vendor/t3docs/fluid-documentation-generator/config/fluidStandalone/viewhelpers_fluid.json