Fluid Documentation Generator Laravel Package

Product Decisions This Supports

• Automated Technical Documentation for Fluid ViewHelpers: Eliminates manual maintenance of reference docs by auto-generating RST files from PHPDoc annotations, reducing technical debt and improving developer onboarding for TYPO3-based projects.
• TYPO3 Ecosystem Integration: Aligns with TYPO3’s documentation pipeline (e.g., render-guides), enabling seamless integration into existing Sphinx-based workflows, which is 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 focus on TYPO3/Fluid makes it a specialized, low-effort 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 new 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 across packages 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). This aligns with modern DevOps practices for maintaining living documentation.
• 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"
     }
     

   • Supports wildcards and multiple configs for large projects.

3. CLI Execution:

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

   • Outputs to fluidDocumentationOutput/ (customizable via FLUID_DOCUMENTATION_OUTPUT_DIR).

4. Integration with render-guides:

   • Use the generated JSON metadata and RST files with TYPO3’s render-guides to produce a static HTML documentation site.
   • Example workflow:

     composer exec fluidDocumentation generate config/*.json
     composer exec render-guides build docs/
     

5. CI/CD Setup:

   • Add to your pipeline (e.g., GitHub Actions) to auto-generate docs on PR merges:

     - name: Generate Documentation
       run: composer exec fluidDocumentation generate config/*.json
     - name: Deploy Docs
       uses: peaceiris/actions-gh-pages@v3
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
         publish_dir: ./fluidDocumentationOutput
     

Key Benefits for Engineers:

• No more manual doc updates: Changes to ViewHelpers automatically reflect in docs.
• Consistent structure: Output follows TYPO3’s documentation standards.
• Extensible: Customize RST templates or JSON schema for project-specific needs.
• Lightweight: Pure PHP, no heavy dependencies.

Next Steps:

• Pilot: Test with [specific ViewHelper package] and measure time saved.
• Expand: Roll out to all TYPO3 extensions requiring Fluid docs.
• Enhance: Customize templates or add PHPDoc validation to enforce documentation standards.

Risks:

• Requires initial setup (config files, CI/CD integration).
• Limited to Fluid ViewHelpers; non-Fluid classes need separate solutions.

Alternatives Considered:

• Manual Sphinx docs (high maintenance).
• Custom scripts (reinventing the wheel).
• This package offers the best balance of automation and TYPO3 integration."