From 0f5a4473abf62bf6fee5c499af9bf681a9fc9723 Mon Sep 17 00:00:00 2001 From: yanyongyu Date: Mon, 27 Dec 2021 22:08:59 +0800 Subject: [PATCH] :memo: add plugin docs --- website/docs/{guide => }/README.md | 2 +- website/docs/README.mdx | 7 - website/docs/advanced/di/_category_.json | 3 + .../{handler => di}/dependency-injection.md | 0 .../docs/advanced/{handler => di}/overload.md | 0 .../advanced/{handler => di}/sync-support.md | 0 website/docs/guide/start/_category_.json | 4 - website/docs/guide/start/installation.md | 122 ------------------ website/docs/guide/tutorial/_category_.json | 4 - .../docs/{guide => }/start/editor-support.md | 0 .../docs/{guide => }/start/install-adapter.md | 0 .../docs/{guide => }/start/install-driver.md | 0 .../docs/{guide => }/start/install-plugin.md | 0 website/docs/start/installation.md | 75 +++++++++++ website/docs/{guide => }/start/nb-cli.md | 0 website/docs/{guide => }/start/question.md | 2 +- .../{guide => }/tutorial/choose-driver.md | 12 +- .../{guide => }/tutorial/configuration.md | 2 +- .../tutorial/creating-a-project.md | 4 +- .../{guide => }/tutorial/custom-logger.md | 0 website/docs/tutorial/plugin/_category_.json | 5 + website/docs/tutorial/plugin/config-plugin.md | 6 + .../docs/tutorial/plugin/create-matcher.md | 11 ++ website/docs/tutorial/plugin/introduction.md | 67 ++++++++++ website/docs/tutorial/plugin/load-plugin.md | 11 ++ .../{guide => }/tutorial/register-adapter.md | 2 +- website/sidebars.js | 101 +++++---------- 27 files changed, 218 insertions(+), 222 deletions(-) rename website/docs/{guide => }/README.md (99%) delete mode 100644 website/docs/README.mdx create mode 100644 website/docs/advanced/di/_category_.json rename website/docs/advanced/{handler => di}/dependency-injection.md (100%) rename website/docs/advanced/{handler => di}/overload.md (100%) rename website/docs/advanced/{handler => di}/sync-support.md (100%) delete mode 100644 website/docs/guide/start/_category_.json delete mode 100644 website/docs/guide/start/installation.md delete mode 100644 website/docs/guide/tutorial/_category_.json rename website/docs/{guide => }/start/editor-support.md (100%) rename website/docs/{guide => }/start/install-adapter.md (100%) rename website/docs/{guide => }/start/install-driver.md (100%) rename website/docs/{guide => }/start/install-plugin.md (100%) create mode 100644 website/docs/start/installation.md rename website/docs/{guide => }/start/nb-cli.md (100%) rename website/docs/{guide => }/start/question.md (87%) rename website/docs/{guide => }/tutorial/choose-driver.md (84%) rename website/docs/{guide => }/tutorial/configuration.md (97%) rename website/docs/{guide => }/tutorial/creating-a-project.md (95%) rename website/docs/{guide => }/tutorial/custom-logger.md (100%) create mode 100644 website/docs/tutorial/plugin/_category_.json create mode 100644 website/docs/tutorial/plugin/config-plugin.md create mode 100644 website/docs/tutorial/plugin/create-matcher.md create mode 100644 website/docs/tutorial/plugin/introduction.md create mode 100644 website/docs/tutorial/plugin/load-plugin.md rename website/docs/{guide => }/tutorial/register-adapter.md (99%) diff --git a/website/docs/guide/README.md b/website/docs/README.md similarity index 99% rename from website/docs/guide/README.md rename to website/docs/README.md index 66312529..57fbb399 100644 --- a/website/docs/guide/README.md +++ b/website/docs/README.md @@ -1,7 +1,7 @@ --- sidebar_position: 0 id: index -slug: /guide +slug: / --- # 概览 diff --git a/website/docs/README.mdx b/website/docs/README.mdx deleted file mode 100644 index 8e3c943b..00000000 --- a/website/docs/README.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -slug: / ---- - -import { Redirect } from "@docusaurus/router"; - -; diff --git a/website/docs/advanced/di/_category_.json b/website/docs/advanced/di/_category_.json new file mode 100644 index 00000000..af708df3 --- /dev/null +++ b/website/docs/advanced/di/_category_.json @@ -0,0 +1,3 @@ +{ + "label": "依赖注入" +} diff --git a/website/docs/advanced/handler/dependency-injection.md b/website/docs/advanced/di/dependency-injection.md similarity index 100% rename from website/docs/advanced/handler/dependency-injection.md rename to website/docs/advanced/di/dependency-injection.md diff --git a/website/docs/advanced/handler/overload.md b/website/docs/advanced/di/overload.md similarity index 100% rename from website/docs/advanced/handler/overload.md rename to website/docs/advanced/di/overload.md diff --git a/website/docs/advanced/handler/sync-support.md b/website/docs/advanced/di/sync-support.md similarity index 100% rename from website/docs/advanced/handler/sync-support.md rename to website/docs/advanced/di/sync-support.md diff --git a/website/docs/guide/start/_category_.json b/website/docs/guide/start/_category_.json deleted file mode 100644 index 8f729133..00000000 --- a/website/docs/guide/start/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "position": 1, - "label": "开始" -} diff --git a/website/docs/guide/start/installation.md b/website/docs/guide/start/installation.md deleted file mode 100644 index 4f430cce..00000000 --- a/website/docs/guide/start/installation.md +++ /dev/null @@ -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 - ``` - - - -:::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 . # 不推荐 -``` - - diff --git a/website/docs/guide/tutorial/_category_.json b/website/docs/guide/tutorial/_category_.json deleted file mode 100644 index df4a90ff..00000000 --- a/website/docs/guide/tutorial/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "position": 2, - "label": "教程" -} diff --git a/website/docs/guide/start/editor-support.md b/website/docs/start/editor-support.md similarity index 100% rename from website/docs/guide/start/editor-support.md rename to website/docs/start/editor-support.md diff --git a/website/docs/guide/start/install-adapter.md b/website/docs/start/install-adapter.md similarity index 100% rename from website/docs/guide/start/install-adapter.md rename to website/docs/start/install-adapter.md diff --git a/website/docs/guide/start/install-driver.md b/website/docs/start/install-driver.md similarity index 100% rename from website/docs/guide/start/install-driver.md rename to website/docs/start/install-driver.md diff --git a/website/docs/guide/start/install-plugin.md b/website/docs/start/install-plugin.md similarity index 100% rename from website/docs/guide/start/install-plugin.md rename to website/docs/start/install-plugin.md diff --git a/website/docs/start/installation.md b/website/docs/start/installation.md new file mode 100644 index 00000000..dfa8d798 --- /dev/null +++ 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 + ``` + + + +:::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 . # 不推荐 +``` diff --git a/website/docs/guide/start/nb-cli.md b/website/docs/start/nb-cli.md similarity index 100% rename from website/docs/guide/start/nb-cli.md rename to website/docs/start/nb-cli.md diff --git a/website/docs/guide/start/question.md b/website/docs/start/question.md similarity index 87% rename from website/docs/guide/start/question.md rename to website/docs/start/question.md index e7f0fcf1..41e30d5c 100644 --- a/website/docs/guide/start/question.md +++ b/website/docs/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 群 (点击下方链接直达) diff --git a/website/docs/guide/tutorial/choose-driver.md b/website/docs/tutorial/choose-driver.md similarity index 84% rename from website/docs/guide/tutorial/choose-driver.md rename to website/docs/tutorial/choose-driver.md index 4363751b..898d9f24 100644 --- a/website/docs/guide/tutorial/choose-driver.md +++ b/website/docs/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 diff --git a/website/docs/guide/tutorial/configuration.md b/website/docs/tutorial/configuration.md similarity index 97% rename from website/docs/guide/tutorial/configuration.md rename to website/docs/tutorial/configuration.md index 0a68666d..94ee90cd 100644 --- a/website/docs/guide/tutorial/configuration.md +++ b/website/docs/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 diff --git a/website/docs/guide/tutorial/creating-a-project.md b/website/docs/tutorial/creating-a-project.md similarity index 95% rename from website/docs/guide/tutorial/creating-a-project.md rename to website/docs/tutorial/creating-a-project.md index 659bdd54..194b651e 100644 --- a/website/docs/guide/tutorial/creating-a-project.md +++ b/website/docs/tutorial/creating-a-project.md @@ -18,8 +18,7 @@ nb create ## 目录结构 - -```bash +```bash title=Project AweSome-Bot ├── "awesome_bot" # 或是 src │ └── "plugins" @@ -33,7 +32,6 @@ AweSome-Bot ├── "pyproject.toml" └── README.md ``` - - `awesome_bot/plugins` 或 `src/plugins`: 用于存放编写的 bot 插件 - `.env`, `.env.dev`, `.env.prod`: 各环境配置文件 diff --git a/website/docs/guide/tutorial/custom-logger.md b/website/docs/tutorial/custom-logger.md similarity index 100% rename from website/docs/guide/tutorial/custom-logger.md rename to website/docs/tutorial/custom-logger.md diff --git a/website/docs/tutorial/plugin/_category_.json b/website/docs/tutorial/plugin/_category_.json new file mode 100644 index 00000000..4ad35288 --- /dev/null +++ b/website/docs/tutorial/plugin/_category_.json @@ -0,0 +1,5 @@ +{ + "position": 7, + "label": "插件", + "collapsible": false +} diff --git a/website/docs/tutorial/plugin/config-plugin.md b/website/docs/tutorial/plugin/config-plugin.md new file mode 100644 index 00000000..e397da91 --- /dev/null +++ b/website/docs/tutorial/plugin/config-plugin.md @@ -0,0 +1,6 @@ +--- +sidebar_position: 2 +description: 规范定义插件配置项 +--- + +# 定义插件配置 diff --git a/website/docs/tutorial/plugin/create-matcher.md b/website/docs/tutorial/plugin/create-matcher.md new file mode 100644 index 00000000..bba6a230 --- /dev/null +++ b/website/docs/tutorial/plugin/create-matcher.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 3 +description: 定义事件响应器，对特定的事件进行处理 + +options: + menu: + weight: 26 + category: guide +--- + +# 定义事件响应器 diff --git a/website/docs/tutorial/plugin/introduction.md b/website/docs/tutorial/plugin/introduction.md new file mode 100644 index 00000000..d85c46b7 --- /dev/null +++ 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 +``` diff --git a/website/docs/tutorial/plugin/load-plugin.md b/website/docs/tutorial/plugin/load-plugin.md new file mode 100644 index 00000000..19071da6 --- /dev/null +++ b/website/docs/tutorial/plugin/load-plugin.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 1 +description: 通过不同方式加载插件 + +options: + menu: + weight: 25 + category: guide +--- + +# 加载插件 diff --git a/website/docs/guide/tutorial/register-adapter.md b/website/docs/tutorial/register-adapter.md similarity index 99% rename from website/docs/guide/tutorial/register-adapter.md rename to website/docs/tutorial/register-adapter.md index c7f72958..98638c1f 100644 --- a/website/docs/guide/tutorial/register-adapter.md +++ b/website/docs/tutorial/register-adapter.md @@ -4,7 +4,7 @@ description: 协议适配器的功能与使用 options: menu: - weight: 26 + weight: 23 category: guide --- diff --git a/website/sidebars.js b/website/sidebars.js index 8786cf3f..b91cd3b6 100644 --- 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" }],