wpjscc / wn-docs-plugin
在 Winter CMS 中阅读和管理文档
Requires
- php: >=7.2.9
- composer/installers: ~1.0
- nikic/php-parser: ^4.11.0
- phpdocumentor/reflection-docblock: ^5.2.2
This package is auto-updated.
Last update: 2024-09-06 14:18:06 UTC
README
将完整文档套件集成到您的 Winter CMS 安装中。文档可以从 Markdown 文件生成,或从 PHP 代码分析。
功能
- 从您的插件或远程 ZIP 文件中本地生成文档。
- 从 Markdown 文件创建基于内容的文档。
- 从 PHP doc-blocks 和解析的 PHP 代码创建 API 文档。
- 可在后端和 CMS 中使用。
入门
要安装此插件,您可以通过 Winter CMS 商场 安装它,或者使用 Composer 安装
composer require winter/wn-docs-plugin
然后,运行迁移以确保插件已启用
php artisan winter:up
注册文档
可以通过将 registerDocumentation
方法添加到您的插件类(Plugin.php
)来注册文档,具体取决于文档是基于内容还是基于 API,以及文档或代码是存储在本地还是远程。
<?php class MyPlugin extends \System\Classes\PluginBase { // ... public function registerDocumentation() { return [ 'guide' => [ 'name' => 'Documentation Guide', 'type' => 'user', 'source' => 'local', 'path' => 'docs' ], ]; } // ... }
该方法应返回一个数组,其中每个项目的键代表文档的 "code",并且数组中的值作为参数
对于 API 文档(即 type
参数为 php
),可以指定一些额外的参数
文档类型
当前 Docs 插件支持两种类型的文档,Markdown(md
)和 PHP(php
)。
Markdown
Markdown 用于生成文本和图像文档,允许在短时间内轻松编写大量文档。Markdown 文档处理器使用 CommonMark 库 确保准确解析 Markdown 并启用这些有用功能
- 自动链接网站和电子邮件地址
- 自动生成目录和锚点标签
- 处理外部链接
- 前情摘要(标题和元定义)
- Markdown 表格
Markdown 文档可以按您希望的方式排列 - 主要目录可以在文档源内的 .yaml
文件中指定。
示例目录 YAML 文件
rootPage: home sections: Introduction: pages: welcome: "Welcome" Functionality: pages: functionality/cool-stuff: "Cool Stuff" functionality/big-things: "Big Things"
示例 Markdown 文档
--- 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 文档涉及解析 PHP 源代码目录,并确定所有源代码对象(如类、命名空间、属性和方法)中可用的 API。
使用出色的 PHP 解析器库,代码被分析,并从类的各个方面(包括提供有关这些签名的上下文的 doc-blocks)的签名中推导出来。
这使得以下类
<?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), ]; } }
可以渲染为可读的文档,概述了可用的属性($title
,$content
)和方法(render()
)。