💡 add config docstring

nonebot/__init__.py

@@ -3,30 +3,30 @@
 
 为方便使用，`nonebot` 模块从子模块导入了部分内容，以下内容可以直接通过 `nonebot` 模块导入:
 
-- `on` => {ref}`nonebot.plugin.on.on`
-- `on_metaevent` => {ref}`nonebot.plugin.on.on_metaevent`
-- `on_message` => {ref}`nonebot.plugin.on.on_message`
-- `on_notice` => {ref}`nonebot.plugin.on.on_notice`
-- `on_request` => {ref}`nonebot.plugin.on.on_request`
-- `on_startswith` => {ref}`nonebot.plugin.on.on_startswith`
-- `on_endswith` => {ref}`nonebot.plugin.on.on_endswith`
-- `on_keyword` => {ref}`nonebot.plugin.on.on_keyword`
-- `on_command` => {ref}`nonebot.plugin.on.on_command`
-- `on_shell_command` => {ref}`nonebot.plugin.on.on_shell_command`
-- `on_regex` => {ref}`nonebot.plugin.on.on_regex`
-- `CommandGroup` => {ref}`nonebot.plugin.on.CommandGroup`
-- `Matchergroup` => {ref}`nonebot.plugin.on.MatcherGroup`
-- `load_plugin` => {ref}`nonebot.plugin.load.load_plugin`
-- `load_plugins` => {ref}`nonebot.plugin.load.load_plugins`
-- `load_all_plugins` => {ref}`nonebot.plugin.load.load_all_plugins`
-- `load_from_json` => {ref}`nonebot.plugin.load.load_from_json`
-- `load_from_toml` => {ref}`nonebot.plugin.load.load_from_toml`
-- `load_builtin_plugin` => {ref}`nonebot.plugin.load.load_builtin_plugin`
-- `load_builtin_plugins` => {ref}`nonebot.plugin.load.load_builtin_plugins`
-- `get_plugin` => {ref}`nonebot.plugin.plugin.get_plugin`
-- `get_loaded_plugins` => {ref}`nonebot.plugin.plugin.get_loaded_plugins`
-- `export` => {ref}`nonebot.plugin.export.export`
-- `require` => {ref}`nonebot.plugin.load.require`
+- `on` => {ref}``on` <nonebot.plugin.on.on>`
+- `on_metaevent` => {ref}``on_metaevent` <nonebot.plugin.on.on_metaevent>`
+- `on_message` => {ref}``on_message` <nonebot.plugin.on.on_message>`
+- `on_notice` => {ref}``on_notice` <nonebot.plugin.on.on_notice>`
+- `on_request` => {ref}``on_request` <nonebot.plugin.on.on_request>`
+- `on_startswith` => {ref}``on_startswith` <nonebot.plugin.on.on_startswith>`
+- `on_endswith` => {ref}``on_endswith` <nonebot.plugin.on.on_endswith>`
+- `on_keyword` => {ref}``on_keyword` <nonebot.plugin.on.on_keyword>`
+- `on_command` => {ref}``on_command` <nonebot.plugin.on.on_command>`
+- `on_shell_command` => {ref}``on_shell_command` <nonebot.plugin.on.on_shell_command>`
+- `on_regex` => {ref}``on_regex` <nonebot.plugin.on.on_regex>`
+- `CommandGroup` => {ref}``CommandGroup` <nonebot.plugin.on.CommandGroup>`
+- `Matchergroup` => {ref}``MatcherGroup` <nonebot.plugin.on.MatcherGroup>`
+- `load_plugin` => {ref}``load_plugin` <nonebot.plugin.load.load_plugin>`
+- `load_plugins` => {ref}``load_plugins` <nonebot.plugin.load.load_plugins>`
+- `load_all_plugins` => {ref}``load_all_plugins` <nonebot.plugin.load.load_all_plugins>`
+- `load_from_json` => {ref}``load_from_json` <nonebot.plugin.load.load_from_json>`
+- `load_from_toml` => {ref}``load_from_toml` <nonebot.plugin.load.load_from_toml>`
+- `load_builtin_plugin` => {ref}``load_builtin_plugin` <nonebot.plugin.load.load_builtin_plugin>`
+- `load_builtin_plugins` => {ref}``load_builtin_plugins` <nonebot.plugin.load.load_builtin_plugins>`
+- `get_plugin` => {ref}``get_plugin` <nonebot.plugin.plugin.get_plugin>`
+- `get_loaded_plugins` => {ref}``get_loaded_plugins` <nonebot.plugin.plugin.get_loaded_plugins>`
+- `export` => {ref}``export` <nonebot.plugin.export.export>`
+- `require` => {ref}``require` <nonebot.plugin.load.require>`
 
 FrontMatter:
     sidebar_position: 0
@@ -64,7 +64,7 @@ def get_driver() -> Driver:
         全局 {ref}`nonebot.drivers.Driver` 对象
 
     异常:
-        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init` 尚未调用)
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
     用法:
         ```python
@@ -84,7 +84,7 @@ def get_app() -> Any:
 
     异常:
         AssertionError: 全局 Driver 对象不是 {ref}`nonebot.drivers.ReverseDriver` 类型
-        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init` 尚未调用)
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
     用法:
         ```python
@@ -106,7 +106,7 @@ def get_asgi() -> Any:
 
     异常:
         AssertionError: 全局 Driver 对象不是 {ref}`nonebot.drivers.ReverseDriver` 类型
-        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init` 尚未调用)
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
     用法:
         ```python
@@ -135,7 +135,7 @@ def get_bot(self_id: Optional[str] = None) -> Bot:
     异常:
         KeyError: 对应 self_id 的 Bot 不存在
         ValueError: 没有传入 self_id 且没有 Bot 可用
-        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init` 尚未调用)
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
     用法:
         ```python
@@ -161,7 +161,7 @@ def get_bots() -> Dict[str, Bot]:
         一个以 {ref}`nonebot.adapters._bot.Bot.self_id` 为键，{ref}`nonebot.adapters._bot.Bot` 对象为值的字典
 
     异常:
-        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init` 尚未调用)
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
     用法:
         ```python

nonebot/config.py

@@ -15,7 +15,7 @@ from datetime import timedelta
 from ipaddress import IPv4Address
 from typing import Any, Set, Dict, Tuple, Union, Mapping, Optional
 
-from pydantic import BaseSettings, IPvAnyAddress
+from pydantic import BaseSettings, IPvAnyAddress, validator
 from pydantic.env_settings import (
     SettingsError,
     EnvSettingsSource,
@@ -125,15 +125,15 @@ class BaseConfig(BaseSettings):
 
 
 class Env(BaseConfig):
-    """
-    运行环境配置。大小写不敏感。
+    """运行环境配置。大小写不敏感。
 
-    将会从 `nonebot.init 参数` > `环境变量` > `.env 环境配置文件` 的优先级读取配置。
+    将会从 `环境变量` > `.env 环境配置文件` 的优先级读取环境信息。
     """
 
     environment: str = "prod"
-    """
-    当前环境名。 NoneBot 将从 `.env.{environment}` 文件中加载配置。
+    """当前环境名。
+
+    NoneBot 将从 `.env.{environment}` 文件中加载配置。
     """
 
     class Config:
@@ -142,36 +142,37 @@ class Env(BaseConfig):
 
 
 class Config(BaseConfig):
-    """
-    NoneBot 主要配置。大小写不敏感。
+    """NoneBot 主要配置。大小写不敏感。
 
     除了 NoneBot 的配置项外，还可以自行添加配置项到 `.env.{environment}` 文件中。
     这些配置将会在 json 反序列化后一起带入 `Config` 类中。
+
+    配置方法参考: [配置](https://v2.nonebot.dev/docs/tutorial/configuration)
     """
 
-    _common_config: dict
     _env_file: str
+    _common_config: Dict[str, Any]
 
     # nonebot configs
     driver: str = "~fastapi"
-    """
-    NoneBot 运行所使用的 `Driver` 。继承自 `nonebot.drivers.Driver` 。
+    """NoneBot 运行所使用的 `Driver` 。继承自 {ref}`nonebot.drivers.Driver` 。
 
     配置格式为 `<module>[:<Driver>][+<module>[:<Mixin>]]*`。
 
     `~` 为 `nonebot.drivers.` 的缩写。
     """
     host: IPvAnyAddress = IPv4Address("127.0.0.1")  # type: ignore
-    """
-    NoneBot 的 HTTP 和 WebSocket 服务端监听的 IP/主机名。
-    """
+    """NoneBot {ref}`nonebot.drivers.ReverseDriver` 服务端监听的 IP/主机名。"""
     port: int = 8080
-    """
-    NoneBot 的 HTTP 和 WebSocket 服务端监听的端口。
-    """
+    """NoneBot {ref}`nonebot.drivers.ReverseDriver` 服务端监听的端口。"""
     log_level: Union[int, str] = "INFO"
-    """
-    配置 NoneBot 日志输出等级，可以为 `int` 类型等级或等级名称，参考 [`loguru 日志等级`](https://loguru.readthedocs.io/en/stable/api/logger.html#levels)。
+    """NoneBot 日志输出等级，可以为 `int` 类型等级或等级名称
+
+    参考 [`loguru 日志等级`](https://loguru.readthedocs.io/en/stable/api/logger.html#levels)。
+
+    :::tip 提示
+    日志等级名称应为大写，如 `INFO`。
+    :::
 
     用法:
         ```conf
@@ -182,14 +183,11 @@ class Config(BaseConfig):
 
     # bot connection configs
     api_timeout: Optional[float] = 30.0
-    """
-    API 请求超时时间，单位: 秒。
-    """
+    """API 请求超时时间，单位: 秒。"""
 
     # bot runtime configs
     superusers: Set[str] = set()
-    """
-    机器人超级用户。
+    """机器人超级用户。
 
     用法:
         ```conf
@@ -197,20 +195,25 @@ class Config(BaseConfig):
         ```
     """
     nickname: Set[str] = set()
-    """
-    机器人昵称。
-    """
+    """机器人昵称。"""
     command_start: Set[str] = {"/"}
-    """
-    命令的起始标记，用于判断一条消息是不是命令。
+    """命令的起始标记，用于判断一条消息是不是命令。
+
+    用法:
+        ```conf
+        COMMAND_START=["/", ""]
+        ```
     """
     command_sep: Set[str] = {"."}
-    """
-    命令的分隔标记，用于将文本形式的命令切分为元组（实际的命令名）。
+    """命令的分隔标记，用于将文本形式的命令切分为元组（实际的命令名）。
+
+    用法:
+        ```conf
+        COMMAND_SEP=["."]
+        ```
     """
     session_expire_timeout: timedelta = timedelta(minutes=2)
-    """
-    等待用户回复的超时时间。
+    """等待用户回复的超时时间。
 
     用法:
         ```conf
@@ -230,3 +233,9 @@ class Config(BaseConfig):
     class Config:
         extra = "allow"
         env_file = ".env.prod"
+
+
+__autodoc__ = {
+    "CustomEnvSettings": False,
+    "BaseConfig": False,
+}

poetry.lock

@@ -561,7 +561,7 @@ six = ">=1.6.1"
 type = "git"
 url = "https://github.com/nonebot/nb-autodoc.git"
 reference = "master"
-resolved_reference = "19f4b1c3e215ca98f6d1e48ba9be7825596fec8a"
+resolved_reference = "56f34218ab931dd568d7a41f2922d2657be7f638"
 
 [[package]]
 name = "nodeenv"