feat(adapter): 添加从环境变量中获取 dev_env 的值判断是否使用 pkg_resources 风格的命名空间包的功能

chore(build_docs): 修改构建文档的脚本，修复问题
chore(pyproject.toml): 更新 sphinx 到 4.0+
docs: 更新文档

alicebot/adapter/__init__.py

@@ -4,6 +4,7 @@
 ============
 所有协议适配器都必须继承自 ``Adapter`` 基类。
 """
+import os
 import time
 import asyncio
 from functools import wraps
@@ -22,7 +23,7 @@
 T_Adapter = TypeVar('T_Adapter', bound='BaseAdapter')
 
 current_config = config.get()
-if current_config is not None and current_config.dev_env:
+if os.getenv('dev_env') == '1' or (current_config is not None and current_config.dev_env):
     # 当处于开发环境时，使用 pkg_resources 风格的命名空间包
     __import__('pkg_resources').declare_namespace(__name__)
 

build_docs.sh

@@ -3,6 +3,7 @@
 python build_rst.py
 cd docs_build || exit
 rm -rf _build
+export dev_env=1
 make markdown
 cd ..
 rm -rf ./docs/api

build_rst.py

@@ -54,11 +54,27 @@ def build_rst(folder):
         shutil.rmtree(os.path.join(docs_build_folder, '_build'))
     clean_docs_build_folder(docs_build_folder)
     build_rst(module_name)
+
+    # 处理 packages
     with os.scandir(os.path.abspath('packages')) as it:
         entry: os.DirEntry
         for entry in it:
             if not entry.name.startswith('.') and entry.is_dir():
                 os.chdir(entry.path)
                 build_rst(os.path.join('alicebot', 'adapter'))
 
+    os.chdir(source_working_dir)
+    # 针对 mirai.event 的特殊操作
+    with open(os.path.join(docs_build_folder, 'adapter', 'mirai', 'event', 'README.rst'), 'r') as fp:
+        rst_str = fp.read()
+    with os.scandir(os.path.join(docs_build_folder, 'adapter', 'mirai', 'event')) as it:
+        entry: os.DirEntry
+        for entry in it:
+            if entry.name != 'README.rst' and entry.is_file():
+                with open(entry.path, 'r') as fp:
+                    rst_str += fp.read()
+    shutil.rmtree(os.path.join(docs_build_folder, 'adapter', 'mirai', 'event'))
+    with open(os.path.join(docs_build_folder, 'adapter', 'mirai', 'event.rst'), 'w') as fp:
+        fp.write(rst_str)
+
     print('Done!')

docs/.vuepress/config.js

@@ -92,6 +92,40 @@ module.exports = {
                     {title: 'alicebot.adapter.cqhttp.exception', path: 'adapter/cqhttp/exception'},
                     {title: 'alicebot.adapter.cqhttp.message', path: 'adapter/cqhttp/message'}
                   ]
+                },
+                {
+                  title: 'alicebot.adapter.mirai',
+                  collapsable: false,
+                  path: '/api/adapter/mirai/',
+                  children: [
+                    {title: 'alicebot.adapter.mirai', path: 'adapter/mirai/'},
+                    {title: 'alicebot.adapter.mirai.config', path: 'adapter/mirai/config'},
+                    {title: 'alicebot.adapter.mirai.event', path: 'adapter/mirai/event'},
+                    {title: 'alicebot.adapter.mirai.exception', path: 'adapter/mirai/exception'},
+                    {title: 'alicebot.adapter.mirai.message', path: 'adapter/mirai/message'}
+                  ]
+                },
+                {
+                  title: 'alicebot.adapter.dingtalk',
+                  collapsable: false,
+                  path: '/api/adapter/dingtalk/',
+                  children: [
+                    {title: 'alicebot.adapter.dingtalk', path: 'adapter/dingtalk/'},
+                    {title: 'alicebot.adapter.dingtalk.config', path: 'adapter/dingtalk/config'},
+                    {title: 'alicebot.adapter.dingtalk.event', path: 'adapter/dingtalk/event'},
+                    {title: 'alicebot.adapter.dingtalk.exception', path: 'adapter/dingtalk/exception'},
+                    {title: 'alicebot.adapter.dingtalk.message', path: 'adapter/dingtalk/message'}
+                  ]
+                },
+                {
+                  title: 'alicebot.adapter.apscheduler',
+                  collapsable: false,
+                  path: '/api/adapter/apscheduler/',
+                  children: [
+                    {title: 'alicebot.adapter.apscheduler', path: 'adapter/apscheduler/'},
+                    {title: 'alicebot.adapter.apscheduler.config', path: 'adapter/apscheduler/config'},
+                    {title: 'alicebot.adapter.apscheduler.event', path: 'adapter/apscheduler/event'}
+                  ]
                 }
               ]
             }

docs/api/README.md

@@ -8,7 +8,7 @@
 AliceBot 机器人对象，定义了机器人的基本方法，读取并储存配置 `Config` ，加载适配器 `Adapter` 和插件 `Plugin`，并进行事件分发。
 
 
-### _property_ `plugins`
+### property `plugins: List[Type[T_Plugin]]`
 
 
 * **返回**
@@ -19,7 +19,7 @@ AliceBot 机器人对象，定义了机器人的基本方法，读取并储存
 
 * **返回类型**
 
-    List[‘T_Plugin’]
+    List[Type[‘T_Plugin’]]
 
 
 
@@ -81,13 +81,13 @@ AliceBot 机器人对象，定义了机器人的基本方法，读取并储存
 
 * **返回**
 
-    被加载的适配器类。
+    被加载的适配器对象。
 
 
 
 * **返回类型**
 
-    Optional[Type[‘T_Adapter’]]
+    Optional[‘T_Adapter’]
 
 
 
@@ -100,3 +100,187 @@ AliceBot 机器人对象，定义了机器人的基本方法，读取并储存
 * **参数**
 
     **path** – 由储存插件的路径文本组成的列表。 `['path/of/plugins/', '/home/xxx/alicebot/plugins']`
+
+
+
+### `get_loaded_adapter_by_name(name)`
+
+按照名称获取已经加载的适配器。
+
+
+* **参数**
+
+    **name** – 适配器名称。
+
+
+
+* **返回**
+
+    获取到的适配器对象。
+
+
+
+* **引发**
+
+    **LookupError** – 找不到此名称的适配器对象。
+
+
+
+### `bot_run_hook(func)`
+
+注册一个 Bot 启动时的函数。
+
+
+* **参数**
+
+    **func** – 被注册的函数。
+
+
+
+* **返回**
+
+    被注册的函数。
+
+
+
+* **返回类型**
+
+    Callable[[‘Bot’], Awaitable[NoReturn]]
+
+
+
+### `bot_exit_hook(func)`
+
+注册一个 Bot 退出时的函数。
+
+
+* **参数**
+
+    **func** – 被注册的函数。
+
+
+
+* **返回**
+
+    被注册的函数。
+
+
+
+* **返回类型**
+
+    Callable[[‘Bot’], Awaitable[NoReturn]]
+
+
+
+### `adapter_startup_hook(func)`
+
+注册一个适配器初始化时的函数。
+
+
+* **参数**
+
+    **func** – 被注册的函数。
+
+
+
+* **返回**
+
+    被注册的函数。
+
+
+
+* **返回类型**
+
+    Callable[[‘T_Adapter’], Awaitable[NoReturn]]
+
+
+
+### `adapter_run_hook(func)`
+
+注册一个适配器运行时的函数。
+
+
+* **参数**
+
+    **func** – 被注册的函数。
+
+
+
+* **返回**
+
+    被注册的函数。
+
+
+
+* **返回类型**
+
+    Callable[[‘T_Adapter’], Awaitable[NoReturn]]
+
+
+
+### `adapter_shutdown_hook(func)`
+
+注册一个适配器关闭时的函数。
+
+
+* **参数**
+
+    **func** – 被注册的函数。
+
+
+
+* **返回**
+
+    被注册的函数。
+
+
+
+* **返回类型**
+
+    Callable[[‘T_Adapter’], Awaitable[NoReturn]]
+
+
+
+### `event_preprocessor_hook(func)`
+
+注册一个事件预处理函数。
+
+
+* **参数**
+
+    **func** – 被注册的函数。
+
+
+
+* **返回**
+
+    被注册的函数。
+
+
+
+* **返回类型**
+
+    Callable[[‘T_Event’], Awaitable[NoReturn]]
+
+
+
+### `event_postprocessor_hook(func)`
+
+注册一个事件后处理函数。
+
+
+* **参数**
+
+    **func** – 被注册的函数。
+
+
+
+* **返回**
+
+    被注册的函数。
+
+
+
+* **返回类型**
+
+    Callable[[‘T_Event’], Awaitable[NoReturn]]