Getting Started

Minimal Steps to First Use

Install the Package Add to your project’s composer.json under require-dev:
```
composer require --dev t3docs/fluid-documentation-generator
```

Create a Configuration File Define a minimal viewhelpers_config.json in your project root:

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

Validate against the schema.

Generate Documentation Run the CLI command:
```
vendor/bin/fluidDocumentation generate viewhelpers_config.json
```
Output appears in fluidDocumentationOutput/YourPackage/.

Render the Output Use render-guides to convert RST to HTML:

composer require --dev typo3/documentation-render-guides
vendor/bin/render-guides fluidDocumentationOutput/

First Use Case: Documenting a Single ViewHelper

For a package with one ViewHelper (e.g., Vendor\YourPackage\ViewHelpers\ExampleViewHelper), the workflow is:

Ensure the ViewHelper has PHPDoc annotations (e.g., @param, @return, @description).
Run the generator with its config file.
The output includes:
- fluidDocumentationOutput/YourPackage/Index.rst (namespace index).
- fluidDocumentationOutput/YourPackage/ExampleViewHelper.rst (ViewHelper-specific RST).
- fluidDocumentationOutput/YourPackage.json (metadata for render-guides).

Implementation Patterns

Workflows

1. Monorepo or Multi-Package Documentation

Use wildcard configs to document multiple packages in one command:

vendor/bin/fluidDocumentation generate config/viewhelpers_*.json

Order matters—configs are processed left-to-right, determining the index page order.

2. CI/CD Integration

Add to your GitHub Actions workflow (e.g., on push to main):

- name: Generate Documentation
  run: |
    composer require --dev t3docs/fluid-documentation-generator
    vendor/bin/fluidDocumentation generate config/*.json
    git add fluidDocumentationOutput/
    git commit -m "chore: update ViewHelper docs [skip ci]"

Tip: Use FLUID_DOCUMENTATION_OUTPUT_DIR=docs/viewhelpers to customize the output path.

3. Customizing RST Templates

Override default templates by:

Copying the package’s templates from vendor/t3docs/fluid-documentation-generator/src/Resources/templates/ to your project (e.g., resources/fluid-docs-templates/).

Setting the FLUID_DOCUMENTATION_TEMPLATE_DIR env var:

FLUID_DOCUMENTATION_TEMPLATE_DIR=resources/fluid-docs-templates vendor/bin/fluidDocumentation generate config.json

4. Extending with Custom Metadata

Annotate ViewHelpers with custom PHPDoc tags (e.g., @category, @example):

/**
 * @category Formatting
 * @example <my:example>Hello</my:example> renders as <strong>Hello</strong>
 */
class ExampleViewHelper extends AbstractViewHelper

The generator will include these in the RST output.

Integration Tips

Laravel-Specific Adaptations

Artisan Command Alias Create a custom Artisan command to wrap the generator:

// app/Console/Commands/GenerateViewHelperDocs.php
namespace App\Console\Commands;
use Illuminate\Console\Command;
class GenerateViewHelperDocs extends Command
{
    protected $signature = 'docs:viewhelpers {config? : Config file path}';
    public function handle()
    {
        $config = $this->argument('config') ?? 'config/viewhelpers.json';
        $this->call('vendor:bin', ['fluidDocumentation', 'generate', $config]);
    }
}

protected $commands = [
    Commands\GenerateViewHelperDocs::class,
];

Now run with:

php artisan docs:viewhelpers

Publishing Configs Publish the package’s example configs to your project:
```
php artisan vendor:publish --provider="T3docs\FluidDocumentationGenerator\FluidDocumentationGeneratorServiceProvider" --tag="config"
```
This copies vendor/t3docs/fluid-documentation-generator/config/ to config/fluid-docs/.

Dynamic Configuration

Generate configs dynamically for all ViewHelper namespaces in your project:

// Generate configs for all ViewHelpers in src/ViewHelpers/
$viewHelperDir = app_path('ViewHelpers');
$configs = [];
foreach (glob($viewHelperDir . '/*ViewHelper.php') as $file) {
    $namespace = str_replace(['/', '.php'], ['\\', ''], $file);
    $configs[] = [
        'name' => basename(dirname($file)),
        'namespaceAlias' => strtolower(basename(dirname($file))),
        'targetNamespace' => 'http://typo3.org/ns/' . str_replace('\\', '/', $namespace),
    ];
}
file_put_contents('config/viewhelpers_dynamic.json', json_encode($configs, JSON_PRETTY_PRINT));

Gotchas and Tips

Pitfalls

Missing PHPDoc Annotations The generator fails silently if ViewHelpers lack @param, @return, or @description tags. Fix: Add minimal annotations:
```
/**
 * @param string $argument Description
 * @return string
 */
```
Namespace Mismatches If targetNamespace in the config doesn’t match the PHP namespace, ViewHelpers won’t appear in the output. Debug: Verify with:
```
vendor/bin/fluidDocumentation generate --debug config.json
```

Output Directory Permissions The generator throws Permission denied if fluidDocumentationOutput/ is unwritable. Fix:

mkdir -p fluidDocumentationOutput && chmod -R 777 fluidDocumentationOutput

Better: Use a writable directory like storage/fluid-docs and set:

FLUID_DOCUMENTATION_OUTPUT_DIR=storage/fluid-docs vendor/bin/fluidDocumentation generate config.json

Fluid Standalone Compatibility For Fluid Standalone (non-TYPO3), ensure your config uses the correct namespace alias (e.g., fluid for Fluid\ViewHelpers).
Cross-Reference Issues If ViewHelpers reference each other (e.g., <my:child> inside <my:parent>), the generator may fail to resolve links. Workaround:
- Process configs in dependency order (parent ViewHelpers first).
- Use the --sort flag (if available in future versions).

Debugging

Dry Run Use --dry-run to preview what would be generated:

vendor/bin/fluidDocumentation generate --dry-run config.json

Verbose Output Enable debug mode for detailed logs:

vendor/bin/fluidDocumentation generate -v config.json

Validate Configs Check JSON schema compliance:

composer require --dev justinrainbow/json-schema
vendor/bin/json-schema-validator validate vendor/t3docs/fluid-documentation-generator/src/Config.schema.json config.json

Extension Points

Custom RST Directives Extend the JSON output by adding custom fields to ViewHelper PHPDoc tags (e.g., @see, @deprecated). Modify the generator’s ViewHelperFinder class to include these in the output JSON.

Post-Processing Hooks Use Laravel’s finished event to trigger post-processing (e.g., copy docs to a web directory):

// app/Providers/AppServiceProvider.php
public function boot()
{
    if ($this->app->runningInConsole()) {
        event('docs.generated', function () {
            $docsDir = storage_path('fluid-docs');
            File::copyDirectory($docsDir, public_path('docs/viewhelpers'));
        });
    }
}

Dynamic Config Generation Override the ConfigLoader to fetch configs from a database or API:

// app/Providers/FluidDocumentationServiceProvider.php
public function register()
{
    $this->app->bind('config-loader', function () {
        return new DynamicConfigLoader();
    });
}

Template Overrides Extend RST templates by copying the package’s templates and modifying them. Key files:
- ViewHelper.rst.twig (per-ViewHelper template).
- `Index

Fluid Documentation Generator Laravel Package