Fluid Documentation Generator Laravel Package

Product Decisions This Supports

• Automated Technical Documentation for Fluid ViewHelpers: Reduces manual effort in maintaining reference documentation by auto-generating RST files from PHPDoc annotations, cutting technical debt and improving developer onboarding for TYPO3-based projects.
• TYPO3 Ecosystem Integration: Aligns with TYPO3’s documentation pipeline (e.g., render-guides and Sphinx), enabling seamless integration into existing workflows—critical for projects deeply embedded in the TYPO3 ecosystem.
• Build vs. Buy Decision: Justifies adoption for projects where Fluid ViewHelpers are core, avoiding reinventing documentation generation from scratch. The package’s specialization in TYPO3/Fluid makes it a low-effort, high-value solution for niche use cases.
• Roadmap for Developer Experience: Enables faster onboarding by providing structured, up-to-date reference documentation tied directly to the codebase, reducing cognitive load for contributors in TYPO3 projects.
• Multi-Package Documentation: Supports generating documentation for multiple ViewHelper packages (via config files) in a single workflow, ideal for large TYPO3 extensions or monorepos where consistency is critical.
• 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), aligning with modern DevOps practices.
• Reduced Documentation Drift: By tying documentation directly to code annotations (e.g., PHPDoc tags), the package minimizes the risk of documentation becoming outdated, a common pain point in open-source and enterprise projects.

When to Consider This Package

Adopt if:

• Your project is TYPO3-based and relies on Fluid ViewHelpers as a templating system (e.g., custom TYPO3 extensions, TYPO3 CMS customizations, or Fluid Standalone projects).
• You need automated, structured documentation in RST format (e.g., for Sphinx or TYPO3’s render-guides), particularly for technical audiences like developers or integrators.
• Your team prioritizes developer experience and wants to reduce manual documentation maintenance, especially for projects with dozens or hundreds of ViewHelpers.
• You’re already using TYPO3’s documentation ecosystem (e.g., render-guides, Sphinx) and need a seamless integration to avoid toolchain fragmentation.
• You have custom ViewHelpers requiring consistent, machine-readable documentation, and your team lacks dedicated documentation specialists.
• You want to standardize documentation output across multiple TYPO3 packages or extensions, ensuring a unified look and feel.

Avoid if:

• Your project uses Laravel/Blade, Symfony/Twig, or any non-Fluid templating system (this package is incompatible and lacks support for non-Fluid PHP classes).
• You require HTML/Markdown output (e.g., for GitHub Pages, Docusaurus, or Laravel’s native docs). This package is RST-only, which may not align with your content strategy.
• Your team lacks TYPO3/Fluid expertise, as the tool assumes familiarity with TYPO3’s documentation workflows (e.g., RST, Sphinx, and render-guides).
• You need real-time documentation (e.g., live API docs or interactive widgets). This is a build-time generator, not a live API or IDE plugin.
• Your project has no ViewHelpers or uses non-Fluid PHP classes without proper PHPDoc annotations (the package relies on docblocks for metadata).
• You’re in a non-TYPO3 PHP project without a commitment to TYPO3’s documentation ecosystem.

Look elsewhere if:

• You need Blade component documentation → Use spatie/laravel-blade-directives + phpDocumentor for Laravel projects.
• You want interactive docs (e.g., Swagger/OpenAPI) → Consider knuckleswtf/scribe for APIs or reactphp/documentation for PHP libraries.
• You’re in a non-TYPO3 PHP project → Evaluate phpDocumentor for general PHP class documentation or erusev/parsedown-extra for Markdown.
• You need Laravel-specific docs → Use Laravel’s built-in php artisan api:docs or integrate with tools like Docusaurus or VuePress for modern documentation sites.
• You require multi-language documentation → This package generates English-only RST by default; consider custom solutions or translation tools like Crowdin or Pootle.

How to Pitch It (Stakeholders)

For Executives/Business Stakeholders

*"This package eliminates a major bottleneck in developer onboarding and maintenance for TYPO3 projects by automating the generation of Fluid ViewHelper documentation. Currently, our team spends X hours per quarter manually updating reference docs—a task prone to errors and drift. By adopting this tool, we can:

• Save [Y] hours annually by replacing manual doc updates with automated RST generation.
• Improve developer productivity by providing always-up-to-date, structured reference materials tied directly to the codebase.
• Reduce technical debt by ensuring documentation stays in sync with ViewHelper changes, cutting support requests from misconfigured templates.

Key Alignment:

• Developer Experience: Faster onboarding for new hires/contributors.
• Cost Efficiency: No ongoing maintenance; just a Composer dependency.
• Ecosystem Fit: Seamlessly integrates with TYPO3’s existing documentation tools (render-guides, Sphinx), avoiding toolchain duplication.

Ask:

• Approval to pilot this for [specific TYPO3 extension/package], targeting a 20% reduction in documentation-related bugs.
• Budget for CI/CD integration to auto-generate docs on PR merges (estimated [$Z] for GitHub Actions setup)."

For Engineering/Technical Stakeholders

*"This tool scans Fluid ViewHelper classes, extracts metadata from PHPDoc annotations, and generates structured RST documentation—ready for Sphinx or TYPO3’s render-guides. Here’s the implementation plan:

1. Installation:

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

   • Add as a dev dependency to avoid bloating production builds.

2. Configuration:

   • Define JSON configs for each ViewHelper namespace (e.g., Vendor\MyPackage\ViewHelpers).
   • Example config:

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

3. CLI Execution:

   vendor/bin/fluidDocumentation generate path/to/config1.json path/to/config2.json
   

   • Supports wildcards and multiple configs (order determines index page hierarchy).

4. Output:

   • Generates:
     • RST files (e.g., fluidDocumentationOutput/MyExtension/Index.rst, MyViewHelper.rst).
     • JSON metadata (e.g., MyExtension.json) for render-guides.
   • Customize output dir via FLUID_DOCUMENTATION_OUTPUT_DIR env var.

5. CI/CD Integration:

   • Add to your pipeline (e.g., GitHub Actions) to auto-generate docs on main branch pushes or PR merges.
   • Example workflow snippet:

     - name: Generate Documentation
       run: composer exec fluidDocumentation generate config/*.json
     

6. Rendering:

   • Use render-guides to convert RST to HTML:

     composer req --dev typo3/documentation-common
     vendor/bin/render-guides fluidDocumentationOutput
     

Benefits:

• Zero manual maintenance: Docs auto-update with code changes.
• Consistent structure: Follows TYPO3’s documentation standards.
• Extensible: Customize RST templates or JSON schema for unique needs.
• Lightweight: Pure PHP, no external dependencies beyond Composer.

Next Steps:

• Validate PHPDoc coverage in your ViewHelpers (e.g., @param, @return tags).
• Propose a pilot project (e.g., a high-maintenance extension) to test integration.
• Discuss CI/CD setup (e.g., publish docs to a static site host like Netlify or GitHub Pages)."