- How do I generate Markdown API docs for a Laravel project using this package?
- Install the package via Composer (`composer require cvuorinen/phpdoc-markdown-public`), then run phpDocumentor with the template path: `./vendor/bin/phpdoc --directory=src/ --target=docs/ --template=vendor/cvuorinen/phpdoc-markdown-public/data/templates/markdown-public`. It will parse PHPDoc blocks and output Markdown for public classes/methods only.
- Will this work with Laravel’s Eloquent models and controllers?
- Yes, it fully supports Laravel’s PHPDoc annotations (e.g., `@property-read`, `@method`). For Eloquent relationships or custom traits, ensure they’re documented with PHPDoc blocks. The template skips private/abstract methods, focusing on the public API.
- Can I integrate this into Laravel’s CI/CD pipeline (e.g., GitHub Actions)?
- Absolutely. Add a step to your workflow to run `composer exec phpdoc` with the template, then commit the generated Markdown to `docs/` or publish it to GitHub Pages. Example: Use `phpdoc` in a job triggered on `push` to `main` or `pull_request`.
- Does this package support Laravel 10+ and PHP 8.1+?
- The package is framework-agnostic but works seamlessly with Laravel 10+ and PHP 8.1+. It relies on phpDocumentor (peer dependency), so ensure you pin a compatible version (e.g., `^3.0`) in `composer.json` to avoid conflicts.
- How do I customize the Markdown output (e.g., add Laravel branding)?
- The template generates GitHub-flavored Markdown, which you can post-process with tools like Pandoc or custom scripts. For Laravel-specific branding, add a header/footer to the output directory or use a static site generator (e.g., Hugo) to theme the docs.
- Will missing PHPDoc annotations break my Laravel application?
- No, this is purely a documentation tool—it won’t affect runtime behavior. However, you can enforce PHPDoc coverage in CI by failing the build if annotations are missing (e.g., using PHP_CodeSniffer or a custom script to validate docs before merging).
- Can I generate docs for private methods or traits in Laravel?
- No, this template intentionally excludes private methods, abstract classes, and non-public traits to focus on the public API. For internal documentation, consider tools like phpDocumentor’s default templates or custom scripts to target specific visibility levels.
- How do I host the generated Markdown docs for a Laravel package?
- Host the `docs/` directory on GitHub Pages (via `gh-pages` branch), Laravel Forge, or a static site generator. For public packages, commit the Markdown to your repo and link to it in your `README.md`. Use GitHub Actions to auto-deploy docs on releases.
- Are there alternatives for Laravel API documentation?
- Alternatives include Swagger/OpenAPI (manual effort) or Laravel API Resources (for structured API docs). However, this package uniquely auto-generates Markdown from PHPDoc, reducing manual work. For dynamic docs, combine it with Laravel Nova/Panel or tools like Readme.io.
- How do I test the documentation generation in a Laravel project?
- Start with a small module (e.g., `AuthController` or `UserService`), add PHPDoc blocks to public methods, then run `phpdoc` locally. Review the `docs/` output for accuracy. Use a `.gitignore` rule to exclude `docs/` unless versioning docs, or commit them to track changes over time.