📝 add plugin docs

website/docs/tutorial/choose-driver.md

@@ -0,0 +1,141 @@
+---
+sidebar_position: 5
+description: 各驱动器的功能与区别
+
+options:
+  menu:
+    weight: 22
+    category: guide
+---
+
+# 选择驱动器
+
+:::warning 注意
+驱动器的选择通常与你所使用的协议适配器相关，如果你不知道该选择哪个驱动器，可以先阅读你想要使用的协议适配器文档说明。
+:::
+
+:::tip 提示
+如何**安装**驱动器请参考 [安装驱动器](../start/install-driver.md)
+
+如何**使用**驱动器请参考 [配置](./configuration.md#driver)
+:::
+
+## 驱动器的类型
+
+驱动器的类型有两种：
+
+- `ForwardDriver`: 即客户端类型驱动器，多用于使用 HTTP 轮询，WebSocket 连接服务器的情形。
+- `ReverseDriver`: 即服务端类型驱动器，多用于使用 WebHook 情形。
+
+其中 `ReverseDriver` 可以配合 `ForwardDriver` 一起使用，即可以同时使用客户端功能和服务端功能。
+
+## 驱动器的功能
+
+在 NoneBot 中，驱动器主要负责数据的收发，不对数据进行处理。通常，驱动器会实现以下功能：
+
+### ForwardDriver
+
+1. 异步发送 HTTP 请求，自定义 `HTTP Method`, `URL`, `Header`, `Body`, `Cookie`, `Proxy`, `Timeout` 等。
+2. 异步建立 WebSocket 连接上下文，自定义 `WebSocket URL`, `Header`, `Cookie`, `Proxy`, `Timeout` 等。
+
+### ReverseDriver
+
+1. 协议适配器自定义 HTTP 上报地址以及对上报数据处理的回调函数。
+2. 协议适配器自定义 WebSocket 连接请求地址以及对 WebSocket 请求处理的回调函数。
+3. 用户可以将 Driver 作为服务端使用，自行添加任何服务端相关功能。
+
+## 内置驱动器
+
+### FastAPI （默认）
+
+类型: `ReverseDriver`
+
+> FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints.
+
+FastAPI 是一个易上手、高性能的异步 Web 框架，具有极佳的编写体验，可以挂载其他 ASGI, WSGI 应用。
+
+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)
+
+```env
+DRIVER=~fastapi
+```
+
+### Quart
+
+类型: `ReverseDriver`
+
+> Quart is an asyncio reimplementation of the popular Flask microframework API.
+
+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)
+
+```env
+DRIVER=~quart
+```
+
+### HTTPX
+
+类型: `ForwardDriver`
+
+:::warning 注意
+本驱动器仅支持 HTTP 请求，不支持 WebSocket 请求。
+:::
+
+> HTTPX is a fully featured HTTP client for Python 3, which provides sync and async APIs, and support for both HTTP/1.1 and HTTP/2.
+
+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)
+
+```env
+DRIVER=~httpx
+```
+
+:::important 注意
+本驱动器支持 `Mixin`
+:::
+
+### websockets
+
+类型: `ForwardDriver`
+
+:::warning 注意
+本驱动器仅支持 WebSocket 请求，不支持 HTTP 请求。
+:::
+
+> websockets is a library for building WebSocket servers and clients in Python with a focus on correctness, simplicity, robustness, and performance.
+
+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)
+
+```env
+DRIVER=~websockets
+```
+
+:::important 注意
+本驱动器支持 `Mixin`
+:::
+
+### AIOHTTP
+
+类型: `ForwardDriver`
+
+> Asynchronous HTTP Client/Server for asyncio and Python.
+
+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)
+
+```env
+DRIVER=~httpx
+```
+
+:::important 注意
+本驱动器支持 `Mixin`
+:::

website/docs/tutorial/configuration.md

@@ -0,0 +1,146 @@
+---
+sidebar_position: 1
+description: 项目配置方式与配置项
+
+options:
+  menu:
+    weight: 21
+    category: guide
+---
+
+# 配置
+
+在上一章节中，我们创建了默认的项目结构，其中 `.env` 和 `.env.*` 均为项目的配置文件，下面将介绍几种 NoneBot 配置方式以及配置项。
+
+:::danger 警告
+请勿将敏感信息写入配置文件并提交至开源仓库！
+:::
+
+## 配置方式
+
+### .env 文件
+
+NoneBot 在启动时将会从系统环境变量或者 `.env` 文件中寻找变量 `ENVIRONMENT` (大小写不敏感)，默认值为 `prod`。  
+这将引导 NoneBot 从系统环境变量或者 `.env.{ENVIRONMENT}` 文件中进一步加载具体配置。
+
+`.env` 文件是基础环境配置文件，该文件中的配置项在不同环境下都会被加载，但会被 `.env.{ENVIRONMENT}` 文件中的配置所覆盖。
+
+NoneBot 使用 [pydantic](https://pydantic-docs.helpmanual.io/) 进行配置处理，并对 `pydantic` 的行为做出了更改，详见下方说明。
+
+现在，我们在 `.env` 文件中写入当前环境信息：
+
+```bash
+# .env
+ENVIRONMENT=dev
+CUSTOM_CONFIG=common config  # 这个配置项在任何环境中都会被加载
+```
+
+如你所想，之后 NoneBot 就会从 `.env.dev` 文件中加载环境变量。
+
+:::important 参考文档
+`.env` 相关文件的加载使用 `dotenv` 语法，请参考 [`dotenv` 文档](https://saurabh-kumar.com/python-dotenv/)
+:::
+
+:::warning 提示
+由于 `pydantic` 使用 JSON 解析配置项，请确保配置项值为 JSON 格式的数据。如：
+
+```bash
+list=["123456789", "987654321", 1]
+test={"hello": "world"}
+```
+
+如果配置项值解析失败将作为 **字符串** 处理。
+
+特别的，如果配置项 **为空** ，则会从 **系统环境变量** 中获取值，如果不存在则为空字符串。
+:::
+
+### .env.\* 文件
+
+NoneBot 默认会从 `.env.{ENVIRONMENT}` 文件加载配置，但是可以在 NoneBot 初始化时指定加载某个环境配置文件: `nonebot.init(_env_file=".env.dev")`，这将忽略你在 `.env` 中设置的 `ENVIRONMENT` 。
+
+配置语法与 `.env` 文件相同。
+
+示例及说明：
+
+```bash
+HOST=0.0.0.0  # 配置 NoneBot 监听的 IP/主机名
+PORT=8080  # 配置 NoneBot 监听的端口
+DEBUG=true  # 开启 debug 模式 **请勿在生产环境开启**
+SUPERUSERS=["123456789", "987654321"]  # 配置 NoneBot 超级用户
+NICKNAME=["awesome", "bot"]  # 配置机器人的昵称
+COMMAND_START=["/", ""]  # 配置命令起始字符
+COMMAND_SEP=["."]  # 配置命令分割字符
+
+# Custom Configs
+CUSTOM_CONFIG1="config in env file"
+CUSTOM_CONFIG2=  # 留空则从系统环境变量读取，如不存在则为空字符串
+```
+
+详细的配置项可以参考 [配置项](#详细配置项) 。
+
+### 系统环境变量
+
+如果在系统环境变量中定义了配置，则一样会被读取。
+
+### bot.py 文件
+
+配置项也可以在 NoneBot 初始化时传入。此处可以传入任意合法 Python 变量。当然也可以在初始化完成后修改或新增。
+
+示例：
+
+```python
+# bot.py
+import nonebot
+
+nonebot.init(custom_config3="config on init")
+
+config = nonebot.get_driver().config
+config.custom_config3 = "changed after init"
+config.custom_config4 = "new config after init"
+```
+
+## 配置优先级
+
+`bot.py` 文件( `nonebot.init` ) > 系统环境变量 > `.env`, `.env.*` 文件
+
+## 读取配置项
+
+配置项可以通过三种类型的对象获取：`driver`, `adapter`, `bot`。
+
+```python
+import nonebot
+# driver
+nonebot.get_driver().config.custom_config
+# bot
+nonebot.get_bot().config.custom_config
+# adapter
+nonebot.get_driver()._adapters["adapter_name"].config.custom_config
+```
+
+## 详细配置项
+
+配置项的 API 文档可以前往 [Class Config](../api/config.md#class-config) 查看。
+
+### Driver
+
+- **类型**: `str`
+- **默认值**: `"~fastapi"`
+
+NoneBot 运行所使用的驱动器。主要分为 `ForwardDriver`, `ReverseDriver` 即客户端和服务端两类。
+
+配置格式采用特殊语法：`<module>[:<Driver>][+<module>[:<Mixin>]]*`
+
+其中 `<module>` 为驱动器模块名，可以使用 `~` 作为 `nonebot.drivers.` 的简写；`<Driver>` 为驱动器类名，默认为 `Driver`；`<Mixin>` 为驱动器混入的类名，默认为 `Mixin`。
+
+NoneBot 内置了几个常用驱动器，包括了各类常用功能，常见驱动器配置如下：
+
+```env
+DRIVER=~fastapi
+DRIVER=~httpx+~websockets
+DRIVER=~fastapi+~httpx+~websockets
+DRIVER=~fastapi+~aiohttp
+```
+
+各驱动器的功能与区别请参考 [选择驱动器](./choose-driver.md) 。
+
+<!-- TODO -->

website/docs/tutorial/creating-a-project.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 0
+description: 创建并运行项目
+
+options:
+  menu:
+    weight: 20
+    category: guide
+---
+
+# 创建项目
+
+可以使用 `nb-cli` 或者自行创建完整的项目目录：
+
+```bash
+nb create
+```
+
+## 目录结构
+
+```bash title=Project
+AweSome-Bot
+├── "awesome_bot" # 或是 src
+│   └── "plugins"
+├── ".env" # 可选的
+├── ".env.dev" # 可选的
+├── ".env.prod" # 可选的
+├── .gitignore
+├── "bot.py"
+├── docker-compose.yml
+├── Dockerfile
+├── "pyproject.toml"
+└── README.md
+```
+
+- `awesome_bot/plugins` 或 `src/plugins`: 用于存放编写的 bot 插件
+- `.env`, `.env.dev`, `.env.prod`: 各环境配置文件
+- `bot.py`: bot 入口文件
+- `pyproject.toml`: 项目插件配置文件
+- `Dockerfile`, `docker-compose.yml`: Docker 镜像配置文件
+
+## 启动 Bot
+
+:::warning 提示
+如果您使用如 `VSCode` / `PyCharm` 等 IDE 启动 nonebot，请检查 IDE 当前工作空间目录是否与当前侧边栏打开目录一致。
+
+> 注意：在二者不一致的环境下可能导致 nonebot 读取配置文件和插件等不符合预期
+
+:::
+
+1. 通过 `nb-cli`
+
+   ```bash
+   nb run [--file=bot.py] [--app=app]
+   ```
+
+   其中 `--file` 参数可以指定 bot 入口文件，默认为 `bot.py`，`--app` 参数可以指定 asgi server，默认为 `app`。
+
+2. 直接通过 `python` 启动
+
+   ```bash
+   python bot.py
+   ```
+
+:::tip 提示
+如果在 bot 入口文件内定义了 asgi server， `nb-cli` 将会为你启动**冷重载模式**（当文件发生变动时自动重启 NoneBot 实例）
+:::

website/docs/tutorial/custom-logger.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 100
+description: 修改日志级别与输出
+---
+
+# 自定义日志

website/docs/tutorial/plugin/_category_.json

@@ -0,0 +1,5 @@
+{
+  "position": 7,
+  "label": "插件",
+  "collapsible": false
+}

website/docs/tutorial/plugin/config-plugin.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 2
+description: 规范定义插件配置项
+---
+
+# 定义插件配置

website/docs/tutorial/plugin/create-matcher.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+description: 定义事件响应器，对特定的事件进行处理
+
+options:
+  menu:
+    weight: 26
+    category: guide
+---
+
+# 定义事件响应器

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
+```

website/docs/tutorial/plugin/load-plugin.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 1
+description: 通过不同方式加载插件
+
+options:
+  menu:
+    weight: 25
+    category: guide
+---
+
+# 加载插件

website/docs/tutorial/register-adapter.md

@@ -0,0 +1,93 @@
+---
+sidebar_position: 6
+description: 协议适配器的功能与使用
+
+options:
+  menu:
+    weight: 23
+    category: guide
+---
+
+# 使用适配器
+
+:::tip 提示
+如何**安装**协议适配器请参考 [安装协议适配器](../start/install-adapter.md)
+:::
+
+## 协议适配器的功能
+
+由于 NoneBot 的跨平台特性，需要支持不同的协议，因此需要对特定的平台协议编写一个转换器。
+
+协议适配器即是充当中间人的转换器，它将驱动器所收到的数据转换为可以被 NoneBot 处理的事件 Event，并将事件传递给 NoneBot。
+
+同时，协议适配器还会处理 API 调用，转换为可以被驱动器处理的数据发送出去。
+
+## 注册协议适配器
+
+NoneBot 在默认情况下并不会加载任何协议适配器，需要自己手动注册。下方是个加载协议适配器的例子：
+
+```python title=bot.py
+import nonebot
+from your_adapter_package import Adapter
+
+nonebot.init()
+driver = nonebot.get_driver()
+driver.register_adapter(Adapter)
+
+nonebot.run()
+```
+
+加载步骤如下：
+
+### 导入协议适配器
+
+首先从你需要的协议适配器的包中导入适配器类，通常为 `Adapter`
+
+```python title=bot.py {2}
+import nonebot
+from your_adapter_package import Adapter
+
+nonebot.init()
+driver = nonebot.get_driver()
+driver.register_adapter(Adapter)
+
+nonebot.run()
+```
+
+### 获得驱动器实例
+
+加载协议适配器需要通过驱动器来进行，因此，你需要先初始化 NoneBot，并获得驱动器实例。
+
+```python title=bot.py {4,5}
+import nonebot
+from your_adapter_package import Adapter
+
+nonebot.init()
+driver = nonebot.get_driver()
+driver.register_adapter(Adapter)
+
+nonebot.run()
+```
+
+### 注册
+
+获得驱动器实例后，你需要调用 `register_adapter` 方法来注册协议适配器。NoneBot 会通过协议适配器的 `get_name` 方法来获得协议适配器的名字。
+
+:::warning 注意
+你可以多次调用来注册多个协议适配器，但不能注册多次相同的协议适配器，发生这种情况时 NoneBot 会给出一个警告并忽略这次注册。
+:::
+
+```python title=bot.py {6}
+import nonebot
+from your_adapter_package import Adapter
+
+nonebot.init()
+driver = nonebot.get_driver()
+driver.register_adapter(Adapter)
+
+nonebot.run()
+```
+
+:::danger 警告
+协议适配器需要在 NoneBot 启动前进行注册，即 `nonebot.run()` 之前，否则会出现未知的错误。
+:::