Fluid Documentation Generator Laravel Package

Product Decisions This Supports

• Automated Developer Documentation for Fluid ViewHelpers: Eliminates manual maintenance of technical reference docs by auto-generating RST files from code annotations, reducing technical debt and improving developer onboarding.
• TYPO3 Ecosystem Integration: Aligns with TYPO3’s documentation pipeline (e.g., render-guides), enabling seamless integration into existing Sphinx-based documentation workflows.
• Build vs. Buy Decision: Justifies adoption for TYPO3-based projects where Fluid ViewHelpers are core, avoiding reinventing documentation generation from scratch.
• Roadmap for Developer Experience: Enables faster onboarding by providing structured, up-to-date reference documentation tied directly to the codebase, reducing cognitive load for new contributors.
• Multi-Package Documentation: Supports generating documentation for multiple ViewHelper packages (via config files) in a single workflow, ideal for large TYPO3 extensions or monorepos.
• CI/CD Integration: Facilitates automated documentation updates in pipelines, ensuring docs stay current with code changes (e.g., trigger on PR merges or nightly builds).

When to Consider This Package

Adopt if:

• Your project is TYPO3-based and relies on Fluid ViewHelpers as a templating system.
• You need automated, structured documentation in RST format (e.g., for Sphinx or TYPO3’s render-guides).
• Your team prioritizes developer experience and wants to reduce manual documentation maintenance.
• You’re already using TYPO3’s documentation ecosystem (e.g., render-guides) and need a seamless integration.
• You have custom ViewHelpers requiring consistent, machine-readable documentation.

Avoid if:

• Your project uses Laravel/Blade, Symfony/Twig, or any non-Fluid templating system (this package is incompatible).
• You require HTML/Markdown output (e.g., for GitHub Pages, Docusaurus, or Laravel’s native docs).
• Your team lacks TYPO3/Fluid expertise, as the tool assumes familiarity with TYPO3’s documentation workflows.
• You need real-time documentation (this is a build-time generator, not a live API).
• Your project has no ViewHelpers or uses non-Fluid PHP classes without proper annotations.

Look elsewhere if:

• You need Blade component documentation → Use spatie/laravel-blade-directives + phpDocumentor.
• You want interactive docs → Consider reactphp/documentation or custom solutions.
• You’re in a non-TYPO3 PHP project → Evaluate phpDocumentor or erusev/parsedown-extra for Markdown.
• You need Laravel-specific docs → Use Laravel’s built-in php artisan api:docs or knuckleswtf/scribe for API documentation.

How to Pitch It (Stakeholders)

For Executives/Business Stakeholders

*"This package automates the generation of technical documentation for TYPO3’s Fluid ViewHelpers, saving our team hundreds of hours annually by eliminating manual doc updates. By integrating with TYPO3’s existing documentation pipeline, it ensures our developer onboarding and reference materials stay accurate, consistent, and aligned with the codebase. The low maintenance cost (just a Composer dependency) and high ROI for developer productivity make this a strategic investment for TYPO3 projects.

Key Benefits:

• Reduces technical debt by auto-generating docs from code annotations.
• Improves onboarding with structured, up-to-date reference materials.
• Aligns with TYPO3’s ecosystem, ensuring compatibility with tools like render-guides.

Ask:

• Approval to adopt for TYPO3 extensions with custom ViewHelpers.
• Budget for documentation workflow improvements (e.g., CI integration for auto-generating docs on PR merges)."

For Engineering/Technical Stakeholders

*"This tool scans Fluid ViewHelper classes, extracts metadata from docblocks, and generates structured RST documentation—ready for Sphinx or TYPO3’s render-guides. Here’s how we’d implement it:

1. Installation: Add as a dev dependency (composer req --dev t3docs/fluid-documentation-generator).
2. Configuration: Define JSON configs for each ViewHelper namespace (e.g., Vendor\MyPackage\ViewHelpers).
3. CLI Integration: Run vendor/bin/fluidDocumentation generate config.json in CI/CD to auto-update docs on code changes.
4. Output: Generates RST files + a JSON metadata dump for advanced rendering.

Why this over manual docs?

• Zero maintenance: Docs stay in sync with code (no stale annotations).
• Scalable: Handles multiple packages via wildcard configs.
• TYPO3-native: Plays well with render-guides for polished output.

Trade-offs:

• RST-only: If you need Markdown/HTML, use phpDocumentor instead.
• TYPO3-specific: Won’t work for Blade or non-Fluid projects.

Proposal:

• Pilot in one TYPO3 extension to validate workflow.
• Integrate with GitHub Actions to regenerate docs on main branch pushes.
• Deprecate manual doc updates for ViewHelpers in favor of auto-generated RST.

Key Ask:

• Engineering buy-in to standardize ViewHelper docblocks (e.g., enforce @param/@return tags).
• CI/CD resources to automate doc generation post-merge."

For Product Managers (Non-TYPO3 Context)

*"This package is not suitable for Laravel or non-TYPO3 projects due to its exclusive focus on TYPO3’s Fluid templating system. For Laravel documentation needs, consider the following alternatives:

• Blade Component Documentation: Use spatie/laravel-blade-directives for Blade-specific docs, combined with phpDocumentor for broader PHP class documentation.
• API Documentation: Leverage Laravel’s built-in php artisan api:docs or knuckleswtf/scribe for interactive API documentation.
• Markdown/HTML Output: Use tools like erusev/parsedown-extra for Markdown-based documentation or integrate with Laravel’s native documentation workflows.

Recommendation:

• For TYPO3 projects: Adopt this package for Fluid ViewHelper documentation.
• For Laravel projects: Evaluate phpDocumentor, Scribe, or Blade-specific tools instead."