irazasyed / docgen
Streamline your Laravel package development with automatic facade documentation using Docgen for Laravel
Installs: 1 614
Dependents: 9
Suggesters: 0
Security: 0
Stars: 20
Watchers: 2
Forks: 1
Open Issues: 2
Requires
- php: >=8.0
Requires (Dev)
- illuminate/support: ^10
- pestphp/pest: ^2.0
- pestphp/pest-plugin-arch: ^2.0
- pestphp/pest-plugin-mock: 2.x-dev
- php-parallel-lint/php-parallel-lint: ^1.3
- rector/rector: ^0.15
This package is auto-updated.
Last update: 2024-10-08 10:10:15 UTC
README
📖 Streamline your Laravel package development with automatic facade documentation using Docgen for Laravel Facade.
Introduction
Docgen for Laravel packages, the ultimate solution for Laravel package developers.
This heroic package automatically generates documentation for your Laravel package facade, eliminating the tedious task of maintaining it yourself.
With this package, IDEs will provide you and the developers using your package with method suggestions, making your development journey a breeze.
Installation
You can install the package via composer:
composer require irazasyed/docgen --dev
Usage
There are a number of ways to use the CLI tool.
Basic
Let's start with the basic usage.
Call the command with the name of the facade:
vendor/bin/docgen -f "Namespace\Path\To\Laravel\Facade::class"
Advanced
Create a new config file in your package's root directory named docgen.php
and add the following code:
<?php return [ 'facade' => Namespace\Path\To\Laravel\Facade::class, // Optional // Path\To\Class::class => [Excluded Methods Array] 'classes' => [], // Global Excluded Methods 'excludedMethods' => [], ];
Run the following command to generate the documentation and apply it to the facade:
vendor/bin/docgen
You can also store the config file elsewhere and provide the path using the -c
or --config
option.
Example:
vendor/bin/docgen -c path/to/docgen.php
Generate Docs for Multiclass Facade
If your Laravel facade is linked to a chain of classes that require documentation, you can provide an array of class names. Additionally, if you want to exclude certain methods from the documentation of a specific class, you can pass an array containing the names of those methods.
To illustrate, consider the following example which demonstrates how to use this approach with the Telegram Bot SDK's Laravel Facade:
<?php // docgen.php return [ 'facade' => Telegram\Bot\Laravel\Facades\Telegram::class, 'classes' => [ \Telegram\Bot\BotsManager::class, \Telegram\Bot\Api::class => [ 'setContainer', 'getWebhookUpdates', ], \Telegram\Bot\Commands\CommandBus::class => [ 'getTelegram', 'setTelegram', ], ], // Global Excluded Methods 'excludedMethods' => [], ];
Call the command to generate and apply the docs.
vendor/bin/docgen
API
generate(string|array $classes, array $globalExcludedMethods = [])
Generate the documentation for given classes.
Parameters
$classes
- The class name or an array of[class => (optional) [excluded methods]]
to generate documentation using its methods.$globalExcludedMethods
- (optional) An array of methods to be excluded when generating docs.
Returns
Docgen
- The Docgen instance.
Example
Docgen::generate([ // Class Name => [Excluded Methods] \App\Some\Class::class => ['method1', 'method2'], \App\Some\OtherClass::class, ])->apply(\Namespace\To\Facade::class); // Apply to Facade.
getDocBlock()
Get the generated documentation.
Returns
string
- The generated documentation.
apply(string $className = '')
Apply the generated documentation to the given class name or defaults to the class used to generate docs.
Parameters
$className
- (optional) The class name to apply the generated documentation to.
Returns
bool
- True if it was successful, false otherwise.
TODO
- Add github action to automatically maintain docs.
Resources
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.