Fluid (ViewHelper) Documentation Generator

Generates a Fluid ViewHelper documentation in reStructured text (.rst) format based on installed schemas from multiple vendors.

How to use

1. Clone the repository or start a fresh project based on namelesscoder/fluid-documentation-generator.
2. Place your schema files in schemas directory in the root path. For example, a schema for version 1.2.3 of a package with the composer name myvendor/my-packge must be copied to schemas/myvendor/my-package/1.2.3/schema.xsd.
3. Run ./bin/generate-fluid-documentation or composer generate
4. Either start a web server or add a virtual host pointing to the public directory, or simply open the index.html file from the public folder and browse the documentation locally.

Each vendor, package and version dir can also be fitted with a metadata.json file containing data that the XSD schema file cannot contain - such as the PHP namespace a package uses and the preferred namespace alias to use. See the section below for detailed information about these metadata manifests.

The command supports exactly three arguments. If you wish to specify the second one, the first must also be specified, and so on. However, the arguments can be empty to make the default value apply.

./bin/generate-fluid-documentation "`pwd`/public/" "" 1
# Or, if you just want defaults but need to specify the last argument:
./bin/generate-fluid-documentation "" "" 1

To explain the command arguments:

1. The public directory into which files are published - by default, this is the public/ directory in the application root folder. Changing this obviously changes where all the public files get created.
2. Not used anymore
3. A boolean (1 / 0) specifying whether to perform a forceful update of all generated files. If this is false, any files that already exist will not be regenerated. Useful if you add this to cron and generate from a collection at regular intervals and don't need to continuously re-write everything. Files that don't yet exist will of course be created.

Get the schemas

git clone git@github.com:typo3/typo3.git core
cd core
composer require -o -n --no-progress typo3/fluid-schema-generator "^2.1"
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

Metadata files

A somewhat restricted set of metadata files can be placed in different levels inside the schemas folder:

• In vendors', packages' and versions' directory, a metadata.json file can be placed. Like .htaccess files these are merged in a way that the more specific files' variables will override the more generic ones (a variable defined in a package overrides the same variable if it is also defined in the vendor's metadata file).

The metadata.json for a vendor may consist of:

{
  "outlets": {
    "github": true,
    "packagist": true
  }
}

And the metadata.json for a package or a specific version of a package may consist of:

{
  "namespace": {
    "alias": "v",
    "php": "\\FluidTYPO3\\Vhs\\ViewHelpers\\"
  },
  "outlets": {
    "github": true,
    "packagist": true,
    "ter": "vhs"
  }
}

(note that the ter outlet value must contain the TYPO3 extension key)

All settings are completely optional. Namespace information gets used when rendering schema and ViewHelper information, and outlets toggled on result in links to those outlets (generated by convention using vendor and package name).

Anything that is defined at a higher level will be inherited to lower levels. For example, a package inherits from the vendor metadata and a version's metadata inherits from the package and vendor.

Supported command line arguments

The command line utility takes exactly three arguments. The arguments are not named and must be passed in sequence.

1. The absolute or relative path to the data folder of the application.
2. The absolute or relative path to the public folder of the application.
3. Not used anymore

Continue reading below to learn more.

Note about serving individual packages/versions etc.

The public folder is generated using a complete $vendor/$package/$version structure, which means that if you serve files over HTTP and manipulate the document root setting, you can serve:

• All packages of a specific vendor (or your own)
• A specific package of a specific vendor (or your own)
• A specific version of a package