📝 add plugin docs

2024-11-27 18:45:05 +08:00 · 2021-12-27 22:08:59 +08:00 · 2021-12-27 22:08:59 +08:00 · 0f5a4473ab
commit 0f5a4473ab
parent 7690f0e640
27 changed files with 218 additions and 222 deletions
--- a/website/docs/guide/README.md
+++ b/website/docs/guide/README.md
@ -1,7 +1,7 @@
 ---
 sidebar_position: 0
 id: index
-slug: /guide
+slug: /
 ---

 # 概览
--- a/website/docs/README.mdx
+++ b/website/docs/README.mdx
@ -1,7 +0,0 @@
---
-slug: /
---
-
-import { Redirect } from "@docusaurus/router";
-
-<Redirect to="guide" />;
--- a/website/docs/advanced/di/_category_.json
+++ b/website/docs/advanced/di/_category_.json
@ -0,0 +1,3 @@
+{
+  "label": "依赖注入"
+}
--- a/website/docs/advanced/handler/dependency-injection.md
+++ b/website/docs/advanced/handler/dependency-injection.md
--- a/website/docs/advanced/handler/overload.md
+++ b/website/docs/advanced/handler/overload.md
--- a/website/docs/advanced/handler/sync-support.md
+++ b/website/docs/advanced/handler/sync-support.md
--- a/website/docs/guide/start/_category_.json
+++ b/website/docs/guide/start/_category_.json
@ -1,4 +0,0 @@
-{
-  "position": 1,
-  "label": "开始"
-}
--- a/website/docs/guide/start/installation.md
+++ b/website/docs/guide/start/installation.md
@ -1,122 +0,0 @@
---
-sidebar_position: 0
-description: 通过脚手架, PyPI, GitHub 安装 NoneBot
-
-options:
-  menu:
-    weight: 10
-    category: guide
---
-
-# 安装 NoneBot
-
-:::warning 注意
-请确保你的 Python 版本 >= 3.7.3。
-:::
-
-:::warning 注意
-请在安装 NoneBot v2 之前卸载 NoneBot v1
-
-```bash
-pip uninstall nonebot
-```
-
-:::
-
-## 通过脚手架安装 (推荐)
-
-1. (可选) 使用你喜欢的 Python 环境管理工具 (如 `poetry`, `venv`, `conda` 等) 创建新的虚拟环境
-2. 使用 `pip` 或 其他包管理工具 安装 `nb-cli`，`nonebot2` 会作为其依赖被一起安装
-
-   ```bash
-   pip install nb-cli
-   ```
-
-<!-- TODO: asciinema for installation -->
-
-:::important 提示
-`nb-cli` 的使用方法详见 [使用脚手架](./nb-cli.md)
-:::
-
-## 不使用脚手架 (纯净安装)
-
-如果你不想使用脚手架，可以直接安装 `nonebot2`，并自行完成开发配置。
-
-```bash
-pip install nonebot2
-# 也可以通过 poetry 安装
-poetry add nonebot2
-```
-
-## 从 GitHub 安装
-
-如果你需要使用最新的（可能**尚未发布**的）特性，可以直接从 GitHub 仓库安装：
-
-:::warning 注意
-直接从 Github 仓库中安装意味着你将使用最新提交的代码，它们并没有进行充分的稳定性测试
-
-在任何情况下请不要将其应用于生产环境!
-:::
-
-```bash title="Install From Github"
-# master分支
-poetry add git+https://github.com/nonebot/nonebot2.git#master
-# dev分支
-poetry add git+https://github.com/nonebot/nonebot2.git#dev
-```
-
-或者在克隆 Git 仓库后手动安装：
-
-```bash
-git clone https://github.com/nonebot/nonebot2.git
-cd nonebot2
-poetry install --no-dev  # 推荐
-pip install .  # 不推荐
-```
-
-<!-- ## 安装适配器
-
-适配器可以通过 `nb-cli` 在创建项目时根据你的选择自动安装，也可以自行使用 `pip` 安装
-
-```bash
-pip install <adapter-name>
-```
-
-```bash
-# 列出所有的适配器
-nb adapter list
-```
-
-## 安装插件
-
-插件可以通过 `nb-cli` 进行安装，也可以自行安装并加载插件。
-
-```bash
-# 列出所有的插件
-nb plugin list
-# 搜索插件
-nb plugin search <plugin-name>
-# 安装插件
-nb plugin install <plugin-name>
-```
-
-如果急于上线 Bot 或想要使用现成的插件，以下插件可作为参考：
-
-### 官方插件
-
- [NoneBot-Plugin-Docs](https://github.com/nonebot/nonebot2/tree/master/packages/nonebot-plugin-docs) 离线文档插件
- [NoneBot-Plugin-Test](https://github.com/nonebot/plugin-test) 本地机器人测试前端插件
- [NoneBot-Plugin-APScheduler](https://github.com/nonebot/plugin-apscheduler) 定时任务插件
- [NoneBot-Plugin-LocalStore](https://github.com/nonebot/plugin-localstore) 本地数据文件存储插件
- [NoneBot-Plugin-Sentry](https://github.com/cscs181/QQ-GitHub-Bot/tree/master/src/plugins/nonebot_plugin_sentry) Sentry 在线日志分析插件
- [NoneBot-Plugin-Status](https://github.com/cscs181/QQ-GitHub-Bot/tree/master/src/plugins/nonebot_plugin_status) 服务器状态查看插件
-
-### 其他插件
-
-还有更多的插件在 [这里](/store) 等着你发现～
-
-## 安装开发环境(可选)
-
-NoneBot v2 全程使用 `VSCode` 搭配 `Pylance` 的开发环境进行开发，在严格的类型检查下，NoneBot v2 具有完善的类型设计与声明。
-
-在围绕 NoneBot v2 进行开发时，使用 `VSCode` 搭配 `Pylance` 进行类型检查是非常推荐的。这有利于统一代码风格及避免低级错误的发生。 -->
--- a/website/docs/guide/tutorial/_category_.json
+++ b/website/docs/guide/tutorial/_category_.json
@ -1,4 +0,0 @@
-{
-  "position": 2,
-  "label": "教程"
-}
--- a/website/docs/guide/start/editor-support.md
+++ b/website/docs/guide/start/editor-support.md
--- a/website/docs/guide/start/install-adapter.md
+++ b/website/docs/guide/start/install-adapter.md
--- a/website/docs/guide/start/install-driver.md
+++ b/website/docs/guide/start/install-driver.md
--- a/website/docs/guide/start/install-plugin.md
+++ b/website/docs/guide/start/install-plugin.md
--- a/website/docs/start/installation.md
+++ b/website/docs/start/installation.md
@ -0,0 +1,75 @@
+---
+sidebar_position: 0
+description: 通过脚手架, PyPI, GitHub 安装 NoneBot
+
+options:
+  menu:
+    weight: 10
+    category: guide
+---
+
+# 安装 NoneBot
+
+:::warning 注意
+请确保你的 Python 版本 >= 3.7.3。
+:::
+
+:::warning 注意
+请在安装 NoneBot v2 之前卸载 NoneBot v1
+
+```bash
+pip uninstall nonebot
+```
+
+:::
+
+## 通过脚手架安装 (推荐)
+
+1. (可选) 使用你喜欢的 Python 环境管理工具 (如 `poetry`, `venv`, `conda` 等) 创建新的虚拟环境
+2. 使用 `pip` 或 其他包管理工具 安装 `nb-cli`，`nonebot2` 会作为其依赖被一起安装
+
+   ```bash
+   pip install nb-cli
+   ```
+
+<!-- TODO: asciinema for installation -->
+
+:::important 提示
+`nb-cli` 的使用方法详见 [使用脚手架](./nb-cli.md)
+:::
+
+## 不使用脚手架 (纯净安装)
+
+如果你不想使用脚手架，可以直接安装 `nonebot2`，并自行完成开发配置。
+
+```bash
+pip install nonebot2
+# 也可以通过 poetry 安装
+poetry add nonebot2
+```
+
+## 从 GitHub 安装
+
+如果你需要使用最新的（可能**尚未发布**的）特性，可以直接从 GitHub 仓库安装：
+
+:::warning 注意
+直接从 Github 仓库中安装意味着你将使用最新提交的代码，它们并没有进行充分的稳定性测试
+
+在任何情况下请不要将其应用于生产环境!
+:::
+
+```bash title="Install From Github"
+# master分支
+poetry add git+https://github.com/nonebot/nonebot2.git#master
+# dev分支
+poetry add git+https://github.com/nonebot/nonebot2.git#dev
+```
+
+或者在克隆 Git 仓库后手动安装：
+
+```bash
+git clone https://github.com/nonebot/nonebot2.git
+cd nonebot2
+poetry install --no-dev  # 推荐
+pip install .  # 不推荐
+```
--- a/website/docs/guide/start/nb-cli.md
+++ b/website/docs/guide/start/nb-cli.md
--- a/website/docs/guide/start/question.md
+++ b/website/docs/guide/start/question.md
@ -9,7 +9,7 @@ description: 如何获取帮助

 1. 点击下方链接前往 GitHub ~~点击 star~~ ，前往 Issues 页面，在 `New Issue` Template 中选择 `Question`

-   [![nonebot2](https://img.shields.io/github/stars/nonebot/nonebot2?style=social)](https://github.com/nonebot/nonebot2)
+   NoneBot2: [![nonebot2](https://img.shields.io/github/stars/nonebot/nonebot2?style=social)](https://github.com/nonebot/nonebot2)

 2. 通过 QQ 群 (点击下方链接直达)

--- a/website/docs/guide/tutorial/choose-driver.md
+++ b/website/docs/guide/tutorial/choose-driver.md
@ -4,7 +4,7 @@ description: 各驱动器的功能与区别

 options:
  menu:
-    weight: 25
+    weight: 22
    category: guide
 ---

@ -56,7 +56,7 @@ FastAPI 是一个易上手、高性能的异步 Web 框架，具有极佳的编

 FastAPI: [文档](https://fastapi.tiangolo.com/), [仓库](https://github.com/tiangolo/fastapi)

-驱动器: [API](../../api/drivers/fastapi.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/fastapi.py)
+驱动器: [API](../api/drivers/fastapi.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/fastapi.py)

 ```env
 DRIVER=~fastapi
@ -72,7 +72,7 @@ Quart 是一个类 Flask 的异步版本，拥有与 Flask 非常相似的接口

 Quart: [文档](https://pgjones.gitlab.io/quart/), [仓库](https://gitlab.com/pgjones/quart)

-驱动器: [API](../../api/drivers/quart.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/quart.py)
+驱动器: [API](../api/drivers/quart.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/quart.py)

 ```env
 DRIVER=~quart
@ -90,7 +90,7 @@ DRIVER=~quart

 HTTPX: [文档](https://www.python-httpx.org/), [仓库](https://github.com/encode/httpx/)

-驱动器: [API](../../api/drivers/httpx.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/httpx.py)
+驱动器: [API](../api/drivers/httpx.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/httpx.py)

 ```env
 DRIVER=~httpx
@ -112,7 +112,7 @@ DRIVER=~httpx

 websockets: [文档](https://websockets.readthedocs.io/en/stable/), [仓库](https://github.com/aaugustin/websockets)

-驱动器: [API](../../api/drivers/websockets.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/websockets.py)
+驱动器: [API](../api/drivers/websockets.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/websockets.py)

 ```env
 DRIVER=~websockets
@ -130,7 +130,7 @@ DRIVER=~websockets

 AIOHTTP: [文档](https://docs.aiohttp.org/en/stable/), [仓库](https://github.com/aio-libs/aiohttp)

-驱动器: [API](../../api/drivers/aiohttp.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/aiohttp.py)
+驱动器: [API](../api/drivers/aiohttp.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/aiohttp.py)

 ```env
 DRIVER=~httpx
--- a/website/docs/guide/tutorial/configuration.md
+++ b/website/docs/guide/tutorial/configuration.md
@ -119,7 +119,7 @@ nonebot.get_driver()._adapters["adapter_name"].config.custom_config

 ## 详细配置项

-配置项的 API 文档可以前往 [Class Config](../../api/config.md#class-config) 查看。
+配置项的 API 文档可以前往 [Class Config](../api/config.md#class-config) 查看。

 ### Driver

--- a/website/docs/guide/tutorial/creating-a-project.md
+++ b/website/docs/guide/tutorial/creating-a-project.md
@ -18,8 +18,7 @@ nb create

 ## 目录结构

-<!-- prettier-ignore-start -->
-```bash
+```bash title=Project
 AweSome-Bot
 ├── "awesome_bot" # 或是 src
 │   └── "plugins"
@ -33,7 +32,6 @@ AweSome-Bot
 ├── "pyproject.toml"
 └── README.md
 ```
-<!-- prettier-ignore-end -->

 - `awesome_bot/plugins` 或 `src/plugins`: 用于存放编写的 bot 插件
 - `.env`, `.env.dev`, `.env.prod`: 各环境配置文件
--- a/website/docs/guide/tutorial/custom-logger.md
+++ b/website/docs/guide/tutorial/custom-logger.md
--- a/website/docs/tutorial/plugin/_category_.json
+++ b/website/docs/tutorial/plugin/_category_.json
@ -0,0 +1,5 @@
+{
+  "position": 7,
+  "label": "插件",
+  "collapsible": false
+}
--- a/website/docs/tutorial/plugin/config-plugin.md
+++ b/website/docs/tutorial/plugin/config-plugin.md
@ -0,0 +1,6 @@
+---
+sidebar_position: 2
+description: 规范定义插件配置项
+---
+
+# 定义插件配置
--- a/website/docs/tutorial/plugin/create-matcher.md
+++ b/website/docs/tutorial/plugin/create-matcher.md
@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+description: 定义事件响应器，对特定的事件进行处理
+
+options:
+  menu:
+    weight: 26
+    category: guide
+---
+
+# 定义事件响应器
--- a/website/docs/tutorial/plugin/introduction.md
+++ b/website/docs/tutorial/plugin/introduction.md
@ -0,0 +1,67 @@
+---
+sidebar_position: 0
+description: 插件入门
+---
+
+# 插件入门
+
+## 插件结构
+
+在编写插件之前，首先我们需要了解一下插件的概念。
+
+在 NoneBot 中，插件可以是 Python 的一个模块 `module` ，也可以是一个包 `package` 。NoneBot 会在导入时对这些模块或包做一些特殊的处理使得他们成为一个插件。
+
+下面详细介绍两种插件的结构：
+
+### 模块插件（单文件形式）
+
+在合适的路径创建一个 `.py` 文件即可。例如在 [创建项目](../creating-a-project.md) 中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件 `foo.py`。
+
+```bash title=Project {4}
+AweSome-Bot
+├── awesome_bot
+│   └── plugins
+|      └── foo.py
+├── .env
+├── .env.dev
+├── .env.prod
+├── .gitignore
+├── bot.py
+├── docker-compose.yml
+├── Dockerfile
+├── pyproject.toml
+└── README.md
+```
+
+这个时候它已经可以被称为一个插件了，尽管它还什么都没做。
+
+### 包插件（文件夹形式）
+
+在合适的路径创建一个文件夹，并在文件夹内创建文件 `__init__.py` 即可。例如在 [创建项目](../creating-a-project.md) 中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件夹 `foo`，并在这个文件夹内创建一个文件 `__init__.py`。
+
+```bash title=Project {4,5}
+AweSome-Bot
+├── awesome_bot
+│   └── plugins
+|      └── foo.py
+|         └── __init__.py
+├── .env
+├── .env.dev
+├── .env.prod
+├── .gitignore
+├── bot.py
+├── docker-compose.yml
+├── Dockerfile
+├── pyproject.toml
+└── README.md
+```
+
+这个时候 `foo` 就是一个合法的 Python 包了，同时也是合法的 NoneBot 插件，插件内容可以在 `__init__.py` 中编写。
+
+## 创建插件
+
+除了通过手动创建的方式以外，还可以通过 `nb-cli` 来创建插件，`nb-cli` 会为你在合适的位置创建一个模板包插件。
+
+```bash
+nb plugin create
+```
--- a/website/docs/tutorial/plugin/load-plugin.md
+++ b/website/docs/tutorial/plugin/load-plugin.md
@ -0,0 +1,11 @@
+---
+sidebar_position: 1
+description: 通过不同方式加载插件
+
+options:
+  menu:
+    weight: 25
+    category: guide
+---
+
+# 加载插件
--- a/website/docs/guide/tutorial/register-adapter.md
+++ b/website/docs/guide/tutorial/register-adapter.md
@ -4,7 +4,7 @@ description: 协议适配器的功能与使用

 options:
  menu:
-    weight: 26
+    weight: 23
    category: guide
 ---

--- a/website/sidebars.js
+++ b/website/sidebars.js
@ -15,80 +15,37 @@
 const sidebars = {
  // By default, Docusaurus generates a sidebar from the docs folder structure
  tutorial: [
+    "index",
    {
-      type: "autogenerated",
-      dirName: "guide",
+      type: "category",
+      label: "开始",
+      items: [
+        {
+          type: "autogenerated",
+          dirName: "start",
+        },
+      ],
+    },
+    {
+      type: "category",
+      label: "教程",
+      items: [
+        {
+          type: "autogenerated",
+          dirName: "tutorial",
+        },
+      ],
+    },
+    {
+      type: "category",
+      label: "进阶",
+      items: [
+        {
+          type: "autogenerated",
+          dirName: "advanced",
+        },
+      ],
    },
-    // {
-    //   type: "category",
-    //   label: "指南",
-    //   items: [
-    //     {
-    //       type: "category",
-    //       label: "开始",
-    //       collapsible: false,
-    //       items: [
-    //         "guide/index",
-    //         "guide/installation",
-    //         "guide/getting-started",
-    //         "guide/creating-a-project",
-    //         "guide/basic-configuration",
-    //       ],
-    //     },
-    //     {
-    //       type: "category",
-    //       label: "编写插件",
-    //       collapsible: false,
-    //       items: [
-    //         "guide/loading-a-plugin",
-    //         "guide/creating-a-plugin",
-    //         "guide/creating-a-matcher",
-    //         "guide/creating-a-handler",
-    //         "guide/end-or-start",
-    //       ],
-    //     },
-    //     {
-    //       type: "category",
-    //       label: "协议适配",
-    //       collapsible: false,
-    //       items: [
-    //         "guide/cqhttp-guide",
-    //         "guide/ding-guide",
-    //         "guide/mirai-guide",
-    //         "guide/feishu-guide",
-    //       ],
-    //     },
-    //   ],
-    // },
-    // {
-    //   type: "category",
-    //   label: "进阶",
-    //   items: [
-    //     {
-    //       type: "category",
-    //       label: "进阶",
-    //       collapsible: false,
-    //       items: [
-    //         "advanced/index",
-    //         "advanced/scheduler",
-    //         "advanced/permission",
-    //         "advanced/runtime-hook",
-    //         "advanced/export-and-require",
-    //         {
-    //           type: "category",
-    //           label: "高级事件处理",
-    //           items: [{ type: "autogenerated", dirName: "advanced/handler" }],
-    //         },
-    //       ],
-    //     },
-    //     {
-    //       type: "category",
-    //       label: "发布",
-    //       collapsible: false,
-    //       items: ["advanced/publish-plugin"],
-    //     },
-    //   ],
-    // },
  ],
  api: [{ type: "autogenerated", dirName: "api" }],