Fluid Documentation Generator Laravel Package

Getting Started

Minimal Steps

1. Install in your Laravel/TYPO3 project (if using Fluid ViewHelpers):

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

2. Create a minimal config file (viewhelpers_config.json):

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

3. Run the generator (adjust paths as needed):

   vendor/bin/fluidDocumentation generate path/to/viewhelpers_config.json
   

4. Verify output in fluidDocumentationOutput/ (or custom dir via FLUID_DOCUMENTATION_OUTPUT_DIR).

First Use Case

Document a custom Fluid ViewHelper in a Laravel/TYPO3 hybrid project:

• Add a ViewHelper class (e.g., src/ViewHelpers/MyCustomViewHelper.php) with proper PHPDoc annotations:

  /**
   * @param string $message
   * @return string
   */
  public function render($message) { ... }
  

• Configure the generator to include this namespace in your JSON config.
• Generate docs and integrate the RST output with your existing Sphinx/TYPO3 documentation pipeline.

Implementation Patterns

Core Workflow

1. Configuration-Driven Generation:

   • Use one config file per ViewHelper namespace (e.g., vendor/t3docs/fluid-documentation-generator/config/typo3/*).
   • Order matters: Config files are processed in the order specified, determining the index page hierarchy.
   • Wildcards supported: Generate docs for multiple configs at once (e.g., generate *.json).

2. Integration with Laravel/TYPO3:

   • For Laravel: Use this only if you’re extending TYPO3’s Fluid system (e.g., custom ViewHelpers in a TYPO3 extension bundled with Laravel).
   • For TYPO3: Integrate with render-guides for RST-to-HTML rendering:

     composer require --dev typo3/documentation-render-guides
     vendor/bin/render-guides generate --source=fluidDocumentationOutput --target=docs/build/html
     

   • CI/CD Pipeline:

     # .github/workflows/docs.yml
     - name: Generate Documentation
       run: vendor/bin/fluidDocumentation generate config/*.json
     - name: Deploy Docs
       uses: peaceiris/actions-gh-pages@v3
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
         publish_dir: docs/build/html
     

3. Template Customization:

   • Override default RST templates by copying files from vendor/t3docs/fluid-documentation-generator/src/Resources/templates/ to your project’s config/fluidDocumentation/templates/.
   • Modify Index.rst.j2, ViewHelper.rst.j2, or Namespace.rst.j2 to match your brand/style.

4. JSON Output Utilization:

   • The generated *.json file contains machine-readable metadata (e.g., ViewHelper signatures, parameters, examples).
   • Use it to power a custom frontend (e.g., a Vue/React component library) or API documentation:

     // Example: Fetch and parse JSON for a dynamic docs site
     fetch('/docs/MyPackage.json')
       .then(res => res.json())
       .then(data => console.log(data.viewHelpers));
     

Laravel-Specific Patterns

• Hybrid Projects: If using Laravel + TYPO3 Fluid, place ViewHelpers in app/ViewHelpers/ and configure the generator to scan this directory:

  {
    "name": "LaravelApp",
    "namespaceAlias": "app",
    "targetNamespace": "http://typo3.org/ns/App/ViewHelpers",
    "viewHelperPaths": ["app/ViewHelpers"]
  }
  

• Artisan Command: Create a custom 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:generate';
      public function handle() {
          $this->call('fluidDocumentation.generate', [
              'config' => base_path('config/fluidDocumentation/*.json')
          ]);
      }
  }
  

  Register it in app/Console/Kernel.php and run with:

  php artisan docs:generate
  

Gotchas and Tips

Pitfalls

1. Non-Fluid Projects:

   • Error: No ViewHelpers found if your project lacks Fluid ViewHelpers.
   • Fix: Ensure your config’s targetNamespace matches an actual PHP namespace containing ViewHelper classes.

2. PHPDoc Annotations:

   • Error: Missing @param/@return tags → incomplete documentation.
   • Fix: Enforce a docblock standard (e.g., via PHPStan or PSR-12) or use a pre-commit hook to validate annotations:

     composer require --dev phpstan/phpstan
     vendor/bin/phpstan analyse --level=5 --configuration=phpstan.neon
     

3. Output Directory Conflicts:

   • Error: Permission denied when writing to fluidDocumentationOutput/.
   • Fix: Set a custom output dir via env:

     FLUID_DOCUMENTATION_OUTPUT_DIR=/tmp/docs vendor/bin/fluidDocumentation generate config.json
     

4. Cross-Referencing Issues:

   • Error: Broken links in RST if ViewHelper namespaces aren’t properly configured.
   • Fix: Use fully qualified namespaces in your JSON config and verify namespaceAlias uniqueness.

5. Fluid Version Mismatch:

   • Error: Unsupported Fluid version if your project uses Fluid <2.12.0.
   • Fix: Upgrade Fluid or use an older version of the generator (e.g., 4.0.0).

Debugging Tips

• Validate Configs: Use the JSON schema validator to catch errors early:

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

• Dry Runs: Test with a subset of configs to isolate issues:

  vendor/bin/fluidDocumentation generate config/test.json
  

• Log Output: Enable verbose mode for debugging:

  vendor/bin/fluidDocumentation generate --verbose config.json
  

Extension Points

1. Custom RST Directives: Extend the JSON output schema to include Laravel-specific metadata (e.g., Blade component equivalents):

   {
     "viewHelpers": {
       "MyViewHelper": {
         "laravelEquivalent": "Blade::render('components/my-view-helper')"
       }
     }
   }
   

   Then modify render-guides to interpret this field.

2. Post-Processing Hooks: Use Laravel’s service providers to manipulate the generated RST/JSON:

   // app/Providers/DocumentationServiceProvider.php
   namespace App\Providers;
   use Illuminate\Support\ServiceProvider;
   class DocumentationServiceProvider extends ServiceProvider {
       public function boot() {
           $this->app->afterResolving('fluidDocumentation', function ($generator) {
               // Hook into the generation process
               $generator->on('postGenerate', function ($outputDir) {
                   // Add custom RST files or modify existing ones
               });
           });
       }
   }
   

3. Dynamic Config Generation: Generate configs programmatically for Laravel packages:

   // Generate config for all ViewHelpers in app/ViewHelpers/
   $viewHelperPaths = [app_path('ViewHelpers')];
   $config = [
       "name" => "DynamicConfig",
       "namespaceAlias" => "dynamic",
       "targetNamespace" => "http://typo3.org/ns/App/DynamicViewHelpers",
       "viewHelperPaths" => $viewHelperPaths
   ];
   file_put_contents(base_path('config/fluidDocumentation/dynamic.json'), json_encode($config, JSON_PRETTY_PRINT));
   

Performance Tips

• Exclude Tests: Configure the generator to skip test directories:

  {
    "viewHelperPaths": ["app/ViewHelpers", "!tests/ViewHelpers"]
  }
  

• Cache Output: Use Laravel’s file caching to avoid regenerating docs on every request:

  // app/Providers/AppServiceProvider.php
  use Illuminate\Support\Facades\Cache;
  public function boot() {
      Cache::remember('fluid_docs_json', now()->addDays(1), function () {
          return json_decode(file_get_contents(storage_path('app/public/docs/MyPackage.json')), true);
      });
  }
  

Laravel-Specific Quirks

• Namespace Collisions: If your Laravel app uses `Vendor\