winter / wn-docs-plugin
Read and manage documentation within Winter CMS
Fund package maintenance!
wintercms
Open Collective
Installs: 2 822
Dependents: 1
Suggesters: 0
Security: 0
Stars: 4
Watchers: 5
Forks: 9
Open Issues: 5
Type:winter-plugin
Requires
- php: >=7.2.9
- composer/installers: ~1.0
- nikic/php-parser: ^4.11.0
- phpdocumentor/reflection-docblock: ^5.2.2
README
Integrates a full suite of documentation direct into your Winter CMS installation. Documentation can be generated from Markdown files or analysed from PHP code.
Features
- Generate documentation locally from your plugin, or from a remote ZIP file.
- Create content-based documentation from Markdown files.
- Create API documentation from PHP doc-blocks and parsed PHP code.
- Can be used in both the Backend and CMS.
Getting started
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
Registering documentation
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:
For API documentation (ie. the type
parameter is php
), there are a couple of extra parameters that may be specified:
Types of Documentation
The Docs plugin currently supports two types of documentation, Markdown (md
) and PHP (php
).
Markdown
Markdown is used for the generation of textual and image-based documentation, allowing for the easy writing of large amounts of documentation in a short amount of time. The Markdown documentation processor uses the CommonMark library to ensure accurate parsing of Markdown and the enabling of these useful features:
- Auto-linking of web and email addresses
- Automatic table of contents generation and anchor tags
- External link handling
- Front matter (title and meta definition)
- Markdown tables
Markdown documentation can be arranged in any way you see fit - the main table of contents can be specific in a .yaml
file available within the documentation source.
Example table of contents YAML file
rootPage: home sections: Introduction: pages: welcome: "Welcome" Functionality: pages: functionality/cool-stuff: "Cool Stuff" functionality/big-things: "Big Things"
Example Markdown document
--- title: Big Things --- # Big Things We have some big things available in this software. ## Awesome Feature One This feature allows you to reach a new level of awesome.
PHP
PHP documentation involves parsing a PHP source code directory and determining the available API within all the source code objects, such as classes, namespaces, properties and methods.
Using the awesome PHP Parser library, the code is analyzed and derived from the signatures of all aspects of a class, as well as doc-blocks written to provide additional context for those signatures.
This allows, for example, the following class:
<?php namespace Acme\Blog; use MarkdownParser; class Post extends \BasePost { public string $title; public string $content; /** * Whether the post is published or not */ protected boolean $published = false; /** * Renders the post and returns an array * * @return array Title and content */ public function render() { return [ 'title' => $this->title, 'content' => MarkdownParser::parse($this->content), ]; } }
To be rendered into a readable documentation that outlines the available properties ($title
, $content
) and method (render()
) as readable documentation.