💡 write config docs

nonebot/config.py

@@ -153,16 +153,18 @@ class Config(BaseConfig):
     """
 
     # nonebot configs
-    driver: str = "nonebot.drivers.fastapi"
+    driver: str = "~fastapi"
     """
     - **类型**: ``str``
-    - **默认值**: ``"nonebot.drivers.fastapi"``
+    - **默认值**: ``"~fastapi"``
 
     :说明:
 
-      NoneBot 运行所使用的 ``Driver`` 。继承自 ``nonebot.driver.BaseDriver`` 。
+      NoneBot 运行所使用的 ``Driver`` 。继承自 ``nonebot.drivers.Driver`` 。
 
-      配置格式为 ``<module>[:<class>]``，默认类名为 ``Driver``。
+      配置格式为 ``<module>[:<Driver>][+<module>[:<Mixin>]]*``。
+
+      ``~`` 为 ``nonebot.drivers.`` 的缩写。
     """
     host: IPvAnyAddress = IPv4Address("127.0.0.1")  # type: ignore
     """
@@ -212,21 +214,6 @@ class Config(BaseConfig):
     """
 
     # bot connection configs
-    api_root: Dict[str, str] = {}
-    """
-    - **类型**: ``Dict[str, str]``
-    - **默认值**: ``{}``
-
-    :说明:
-
-      以机器人 ID 为键，上报地址为值的字典，环境变量或文件中应使用 json 序列化。
-
-    :示例:
-
-    .. code-block:: default
-
-        API_ROOT={"123456": "http://127.0.0.1:5700"}
-    """
     api_timeout: Optional[float] = 30.0
     """
     - **类型**: ``Optional[float]``
@@ -236,38 +223,6 @@ class Config(BaseConfig):
 
       API 请求超时时间，单位: 秒。
     """
-    access_token: Optional[str] = None
-    """
-    - **类型**: ``Optional[str]``
-    - **默认值**: ``None``
-
-    :说明:
-
-      API 请求以及上报所需密钥，在请求头中携带。
-
-    :示例:
-
-    .. code-block:: http
-
-        POST /cqhttp/ HTTP/1.1
-        Authorization: Bearer kSLuTF2GC2Q4q4ugm3
-    """
-    secret: Optional[str] = None
-    """
-    - **类型**: ``Optional[str]``
-    - **默认值**: ``None``
-
-    :说明:
-
-      HTTP POST 形式上报所需签名，在请求头中携带。
-
-    :示例:
-
-    .. code-block:: http
-
-        POST /cqhttp/ HTTP/1.1
-        X-Signature: sha1=f9ddd4863ace61e64f462d41ca311e3d2c1176e2
-    """
 
     # bot runtime configs
     superusers: Set[str] = set()

website/docs/guide/basic-configuration.md

@@ -1,95 +0,0 @@
----
-sidebar_position: 5
-
-options:
-  menu:
-    weight: 50
-    category: guide
----
-
-# 基本配置
-
-到目前为止我们还在使用 NoneBot 的默认行为，在开始编写自己的插件之前，我们先尝试在配置文件上动动手脚，让 NoneBot 表现出不同的行为。
-
-在上一章节中，我们创建了默认的项目结构，其中 `.env` 和 `.env.*` 均为项目的配置文件，下面将介绍几种 NoneBot 配置方式。
-
-:::danger 警告
-请勿将敏感信息写入配置文件并提交至开源仓库！
-:::
-
-## .env 文件
-
-NoneBot 在启动时将会从系统环境变量或者 `.env` 文件中寻找变量 `ENVIRONMENT` (大小写不敏感)，默认值为 `prod`。  
-这将引导 NoneBot 从系统环境变量或者 `.env.{ENVIRONMENT}` 文件中进一步加载具体配置。
-
-`.env` 文件是基础环境配置文件，该文件中的配置项在不同环境下都会被加载，但会被 `.env.{ENVIRONMENT}` 文件中的配置所覆盖。
-
-现在，我们在 `.env` 文件中写入当前环境信息：
-
-```bash
-# .env
-ENVIRONMENT=dev
-CUSTOM_CONFIG=common config  # 这个配置项在任何环境中都会被加载
-```
-
-如你所想，之后 NoneBot 就会从 `.env.dev` 文件中加载环境变量。
-
-## .env.\* 文件
-
-NoneBot 使用 [pydantic](https://pydantic-docs.helpmanual.io/) 进行配置管理，会从 `.env.{ENVIRONMENT}` 文件中获悉环境配置。
-
-可以在 NoneBot 初始化时指定加载某个环境配置文件: `nonebot.init(_env_file=".env.dev")`，这将忽略你在 `.env` 中设置的 `ENVIRONMENT` 。
-
-:::warning 提示
-由于 `pydantic` 使用 JSON 解析配置项，请确保配置项值为 JSON 格式的数据。如：
-
-```bash
-list=["123456789", "987654321", 1]
-test={"hello": "world"}
-```
-
-如果配置项值解析失败将作为字符串处理。
-:::
-
-示例及说明：
-
-```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=  # 留空则从系统环境变量读取，如不存在则为空字符串
-```
-
-详细的配置项参考 [Config Reference](../api/config.md) 。
-
-## 系统环境变量
-
-如果在系统环境变量中定义了配置，则一样会被读取。
-
-## 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.*` 文件

website/docs/guide/start/install-adapter.md

@@ -37,4 +37,4 @@ nb adapter install
 pip install <adapter-name>
 ```
 
-<!-- asciinema for install adapter -->
+<!-- TODO: asciinema for install adapter -->

website/docs/guide/start/install-driver.md

@@ -39,4 +39,4 @@ nb driver install
 pip install <driver-name>
 ```
 
-<!-- asciinema for install driver -->
+<!-- TODO: asciinema for install driver -->

website/docs/guide/start/install-plugin.md

@@ -37,4 +37,4 @@ nb plugin install
 pip install <plugin-name>
 ```
 
-<!-- asciinema for install plugin -->
+<!-- TODO: asciinema for install plugin -->

website/docs/guide/start/installation.md

@@ -32,7 +32,7 @@ pip uninstall nonebot
    pip install nb-cli
    ```
 
-<!-- asciinema for installation -->
+<!-- TODO: asciinema for installation -->
 
 :::important 提示
 `nb-cli` 的使用方法详见 [使用脚手架](./nb-cli.md)

website/docs/guide/start/nb-cli.md

@@ -10,4 +10,4 @@ options:
 
 # 使用脚手架
 
-<!-- TODO -->
+<!-- TODO: nb-cli docs -->

website/docs/guide/tutorial/choose-driver.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 5
+description: 各驱动器的功能与区别
+
+options:
+  menu:
+    weight: 25
+    category: guide
+---
+
+# 选择驱动器

website/docs/guide/tutorial/configuration.md

@@ -0,0 +1,144 @@
+---
+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 内置了几个常用驱动器，包括了各类常用功能，常见驱动器配置如下：
+
+- `~fastapi`
+- `~httpx+~websockets`
+- `~fastapi+~httpx+~websockets`
+- `~fastapi+~aiohttp`
+
+各驱动器的功能与区别请参考 [选择驱动器](./choose-driver.md) 。
+
+<!-- TODO -->