wpjscc/wn-docs-plugin

在 Winter CMS 中阅读和管理文档

安装: 34

依赖: 1

建议者: 0

安全: 0

星级: 0

关注者: 1

分支: 9

类型:winter-plugin

dev-main 2023-07-31 08:20 UTC

This package is auto-updated.

Last update: 2024-09-06 14:18:06 UTC


README

GitHub Workflow Status (branch) Codecov Discord

将完整文档套件集成到您的 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())。