Fluid Documentation Generator Laravel Package

Technical Evaluation

Architecture Fit

• Specialized for TYPO3/Fluid Ecosystem: The package is exclusively designed for Fluid ViewHelpers, making it a perfect fit for TYPO3-based projects (e.g., custom extensions, TYPO3 CMS, or Fluid Standalone). For Laravel projects, this is non-applicable unless leveraging Fluid via a bridge (e.g., Laravel Fluid), which would require significant customization.
• RST-Centric Workflow: Aligns with TYPO3’s documentation pipeline (Sphinx + render-guides), but not Laravel’s native stack (Blade, Markdown, or HTML). If your team uses Docusaurus, Markdown, or Laravel’s php artisan docs, this package introduces friction due to format mismatches.
• PHPDoc Dependency: Relies on annotated ViewHelper classes (e.g., @param, @return, @description). Laravel’s Blade components or non-Fluid PHP classes would need retroactive annotation, adding technical debt if not already documented.

Integration Feasibility

• Laravel Compatibility: Low to None without a Fluid integration layer. Key blockers:
  • No support for Blade directives or Laravel-specific components.
  • RST output is TYPO3-centric (e.g., assumes render-guides for rendering), which is non-standard for Laravel.
  • No Laravel service provider or Facade—pure CLI tool with no hooks into Laravel’s lifecycle.
• Workarounds for Laravel:
  • Option 1: Use only for Fluid-based templating in Laravel (e.g., via Laravel Fluid). Requires:
    • Installing Fluid as a dependency.
    • Annotating ViewHelpers with PHPDoc.
    • Running the generator in a custom CI step (e.g., GitHub Actions).
  • Option 2: Abandon RST and post-process output to Markdown/HTML (manual effort).
  • Option 3: Replace entirely with Laravel-native tools (e.g., phpDocumentor + custom templates).
• TYPO3 Projects: High feasibility—designed for TYPO3’s workflow. Example:
  • Install in a TYPO3 extension or monorepo.
  • Configure JSON schemas for each ViewHelper namespace.
  • Integrate into TYPO3’s documentation pipeline (e.g., render-guides).

Technical Risk

• Running only on specific branches (e.g., main).
• Caching generated RST/JSON to avoid full regeneration.
• Parallelizing config file processing. | | Output Customization| Limited control over RST templates or JSON structure. Extending functionality requires forking the package. | Review default templates in the repo. If customization is critical, assess forking effort vs. building an alternative. | | Laravel Ecosystem | No Laravel-specific integrations (e.g., no artisan commands, no Vite/Inertia support). | Treat as a standalone CLI tool—integrate via custom scripts or GitHub Actions workflows. |

Key Questions

1. Is Fluid a Core Part of Your Laravel Project?
   • If yes: Proceed with integration (see Integration Approach).
   • If no: Evaluate alternative tools (e.g., phpDocumentor, erusev/parsedown-extra).
2. What’s Your Documentation Output Format?
   • RST/Sphinx: High fit for TYPO3 projects.
   • Markdown/HTML: Requires post-processing or abandonment.
3. Do Your ViewHelpers Have PHPDoc Annotations?
   • If no: Budget time for retroactive annotation or tooling to auto-generate docs.
4. How Will Docs Fit Into Your CI/CD?
   • Example workflow:

     # GitHub Actions example
     - name: Generate Fluid Docs
       run: composer exec fluidDocumentation generate config/*.json
       if: github.ref == 'refs/heads/main'
     

5. Will You Need to Customize Templates?
   • If yes: Assess forking effort or template override mechanisms.
6. What’s the Long-Term Maintenance Plan?
   • The package is TYPO3-focused with low activity (1 star, 0 dependents). Plan for:
     • Forking if critical bugs arise.
     • Alternative solutions if TYPO3/Fluid adoption wanes.

Integration Approach

Stack Fit

Migration Path

For TYPO3 Projects (High Fit)

1. Installation:

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

2. Configure:
   • Create JSON config files for each ViewHelper namespace (see schema).
   • Example:

     {
       "name": "MyTYPO3Extension",
       "namespaceAlias": "myext",
       "targetNamespace": "http://typo3.org/ns/Vendor/MyExtension/ViewHelpers"
     }
     

3. Generate Docs:

   vendor/bin/fluidDocumentation generate config/*.json
   

   • Output: fluidDocumentationOutput/ (customizable via FLUID_DOCUMENTATION_OUTPUT_DIR).
4. Integrate with render-guides:
   • Use the generated JSON + RST with TYPO3’s render-guides for final rendering.
5. CI/CD Setup:
   • Add to pipeline (e.g., GitHub Actions):

     - name: Generate Documentation
       run: |
         composer install --dev
         vendor/bin/fluidDocumentation generate config/*.json
     

For Laravel Projects (Low Fit)

1. Option A: Use Only for Fluid Components (If Applicable)
   • Install Laravel Fluid (e.g., laravel-fluid/fluid).
   • Follow TYPO3 integration steps above.
2. Option B: Abandon RST (Recommended for Most Laravel Projects)
   • Replace with:
     • phpDocumentor for PHP