Integrates a full suite of documentation direct into your Winter CMS installation. Documentation can be generated from Markdown files or analysed from PHP code.
- Generate documentation locally from your plugin, or from a remote ZIP file.
- Create content-based documentation from Markdown files.
- Create API documentation from PHP docblocks and parsed PHP code.
- Can be used in both the Backend and CMS.
To install the plugin, you may install it through the Winter CMS Marketplace, or you may install it using Composer:
composer require winter/wn-docs-plugin
Then, run the migrations to ensure the plugin is enabled:
php artisan winter:up
Documentation can be registered by adding a registerDocumentation
method to your Plugin class (Plugin.php
), and will depend on whether the documentation is content-based or API-based, and whether the documentation or code is stored locally or remotely.
<?php
class MyPlugin extends \System\Classes\PluginBase
{
// ...
public function registerDocumentation()
{
return [
'guide' => [
'name' => 'Documentation Guide',
'type' => 'user',
'source' => 'local',
'path' => 'docs'
],
];
}
// ...
}
The method should return an array, with the key of each item representing the "code" of the documentation, and the following parameters in an array as the value:
Parameter | Required | Description |
---|---|---|
name |
Yes | The name of this documentation. This will be displayed in documentation lists. |
type |
Yes | The type of documentation. It must be one of the following: user , developer , api or event . See the Types of Documentation for more information. |
source |
Yes | Where the documentation can be sourced from. Must be either local or remote . |
path |
No | If source is local, this will determine the path - relative to the plugin root - that the documentation or code can be found. Not needed if the source is remote . |
url |
No | If source is remote, this will determine the URL to download the documentation source from. The URL must point to a ZIP file that can be extracted. Not needed if the source is local . |
zipFolder |
No | If source is remote, this will allow you to limit the source to a folder within the ZIP file, if the ZIP includes other files. Not needed if the source is local . |
tocPath |
No | Determines the path, relative to the source, where the table of contents YAML file can be found. By default, the Docs plugin will look for a toc.yaml in the root folder of the documentation source. |
image |
No | Provides an image representation of the documentation. |
ignorePaths |
No | An array of paths to ignore when finding available documentation. Each path may be specified as a glob. |
For API documentation (ie. the type
parameter is api
or event
), there are a couple of extra parameters that may be specified:
Parameter | Description |
---|---|
sourcePaths |
An array of paths to limit the API parser to. Each path may be specified as a glob. If no source paths are provided, all PHP files are parsed. Note that the ignorePaths patterns are still applied. |