Weave Code
Fluid Documentation Generator Laravel Package
t3docs/fluid-documentation-generator
Generates automatic Fluid ViewHelper reference documentation in RST format from JSON config files, including navigable namespace and ViewHelper pages plus a JSON asset for rendering with render-guides.
Fluid ViewHelper Static Documentation Site Generator
Frequently asked questions about Fluid Documentation Generator
- What is t3docs/fluid-documentation-generator used for?
- It is a build-time CLI that generates Fluid ViewHelper reference documentation from JSON configuration files. It scans a Composer project for ViewHelper classes, extracts metadata from PHPDoc, and writes an RST directory tree plus a JSON manifest for render-guides. It is intended for projects that contain Fluid ViewHelpers, not for runtime documentation or general API reference generation.
- Can I use t3docs/fluid-documentation-generator in a Laravel app with Blade components?
- Not directly. The generator only discovers and documents Fluid ViewHelper classes; it has no support for Blade components, Blade directives, or Illuminate\View classes. It is a fit only for Laravel or PHP projects that actually ship Fluid ViewHelpers, such as packages targeting Flow or TYPO3-adjacent consumers. If your Laravel app uses Blade only, you need a different documentation tool.
- How do I install t3docs/fluid-documentation-generator?
- Install it as a dev dependency with composer req --dev t3docs/fluid-documentation-generator inside the Composer project that contains the ViewHelpers you want to document. The package must be installed in that host project because it discovers ViewHelpers through the Composer autoloader rather than from a separate input directory. It is not intended to be shipped as a production runtime dependency.
- How do I configure which ViewHelpers get documented?
- Create one or more JSON config files that validate against the package's Config.schema.json. Each config must define at least name, namespaceAlias, and targetNamespace; the generator uses those values to scan the configured PHP namespace and group output by namespace. You can pass multiple config files to control the order of entries on the generated index page.
- How do I run the documentation generator?
- Run vendor/bin/fluidDocumentation generate followed by one or more JSON config file paths, for example vendor/bin/fluidDocumentation generate viewhelpers1_config.json. You can use shell wildcards for config files, and the order of the arguments determines the order on the index page. Output goes to fluidDocumentationOutput by default, and you can override that with the FLUID_DOCUMENTATION_OUTPUT_DIR environment variable.
- What output does the generator produce, and do I need render-guides?
- It produces an RST directory tree with index pages, per-namespace groupings, and one file per ViewHelper, plus a JSON manifest containing namespace and ViewHelper metadata. RST rendering is not included. To turn the output into a browsable documentation site you typically use render-guides, which provides a custom RST directive for the generated JSON and must be adopted alongside the generator.
- Does it generate Markdown for Docusaurus, MkDocs, or GitHub Pages?
- No. The generator emits RST and JSON only, so Markdown-based documentation stacks require a conversion layer that you own and maintain. If you need Docusaurus, MkDocs, or GitHub Pages output, plan for extra work or consider a different documentation pipeline. The generated JSON can be consumed by a custom renderer if you do not want to use render-guides.
- What PHP and typo3fluid/fluid versions does it require?
- Check the package's composer.json for the exact PHP and typo3fluid/fluid constraints before adopting it. Discovery relies on Fluid's ViewHelperFinder, which was introduced in typo3fluid/fluid 2.12 and was rewritten in the generator's 4.0 release. Your project's PHP version and Fluid version must both satisfy those constraints; Laravel's own version is irrelevant because the package does not integrate with Blade.
- Can I use it in CI to catch undocumented ViewHelper changes?
- Yes. Because the generated output is deterministic and ViewHelpers are sorted for consistent results, you can run the generator in CI and diff the output to catch documentation drift. Commit the generated RST and JSON, or compare a freshly generated directory against the committed baseline. This works best when PHPDoc is treated as part of the review process, since output quality depends on docblock quality.
- What are the production and licensing concerns?
- It is a dev-only build tool, so production runtime artifacts are unaffected as long as you keep it in require-dev. The package is LGPL-3.0 licensed, which imposes minimal obligations for normal dev-time use; obligations increase only if you fork and redistribute it. The bigger operational concern is adopting render-guides and its RST/Sphinx toolchain in lockstep with the generator's JSON schema.
Weaver
How can I help you explore Laravel packages today?