add nonebot.typing docs

nonebot/__init__.py

@@ -10,19 +10,19 @@ _driver: Optional[Driver] = None
 
 def get_driver() -> Union[NoReturn, Driver]:
     """
-    - **说明**:
+    :说明:
 
       获取全局 Driver 对象。可用于在计划任务的回调中获取当前 Driver 对象。
 
-    - **返回**:
+    :返回:
 
       * ``Driver``: 全局 Driver 对象
 
-    - **异常**:
+    :异常:
 
       * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
 
-    - **用法**:
+    :用法:
 
     .. code-block:: python
 
@@ -36,19 +36,19 @@ def get_driver() -> Union[NoReturn, Driver]:
 
 def get_app():
     """
-    - **说明**:
+    :说明:
 
       获取全局 Driver 对应 Server App 对象。
 
-    - **返回**:
+    :返回:
 
       * ``Any``: Server App 对象
 
-    - **异常**:
+    :异常:
 
       * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
 
-    - **用法**:
+    :用法:
 
     .. code-block:: python
 
@@ -61,19 +61,19 @@ def get_app():
 
 def get_asgi():
     """
-    - **说明**:
+    :说明:
 
       获取全局 Driver 对应 Asgi 对象。
 
-    - **返回**:
+    :返回:
 
       * ``Any``: Asgi 对象
 
-    - **异常**:
+    :异常:
 
       * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
 
-    - **用法**:
+    :用法:
 
     .. code-block:: python
 
@@ -86,19 +86,19 @@ def get_asgi():
 
 def get_bots() -> Dict[str, Bot]:
     """
-    - **说明**:
+    :说明:
 
       获取所有通过 ws 连接 NoneBot 的 Bot 对象。
 
-    - **返回**:
+    :返回:
 
       * ``Dict[str, Bot]``: 一个以字符串 ID 为键，Bot 对象为值的字典
 
-    - **异常**:
+    :异常:
 
       * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
 
-    - **用法**:
+    :用法:
 
     .. code-block:: python
 
@@ -121,22 +121,24 @@ except ImportError:
 
 def init(*, _env_file: Optional[str] = None, **kwargs):
     """
-    - **说明:**
+    :说明:
 
       初始化 NoneBot 以及 全局 Driver 对象。
+
       NoneBot 将会从 .env 文件中读取环境信息，并使用相应的 env 文件配置。
+
       你也可以传入自定义的 _env_file 来指定 NoneBot 从该文件读取配置。
 
-    - **参数:**
+    :参数:
 
       * ``_env_file: Optional[str]``: 配置文件名，默认从 .env.{env_name} 中读取配置
       * ``**kwargs``: 任意变量，将会存储到 Config 对象里
 
-    - **返回:**
+    :返回:
 
       - `None`
 
-    - **用法:**
+    :用法:
 
     .. code-block:: python
 
@@ -168,22 +170,22 @@ def run(host: Optional[str] = None,
         *args,
         **kwargs):
     """
-    - **说明:**
+    :说明:
 
       启动 NoneBot，即运行全局 Driver 对象。
 
-    - **参数:**
+    :参数:
 
       * ``host: Optional[str]``: 主机名／IP，若不传入则使用配置文件中指定的值
       * ``port: Optional[int]``: 端口，若不传入则使用配置文件中指定的值
       * ``*args``: 传入 Driver.run 的位置参数
       * ``**kwargs``: 传入 Driver.run 的命名参数
 
-    - **返回:**
+    :返回:
 
       - `None`
 
-    - **用法:**
+    :用法:
 
     .. code-block:: python
 

nonebot/typing.py

@@ -1,5 +1,24 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+"""
+类型
+====
+
+下面的文档中，「类型」部分使用 Python 的 Type Hint 语法，见 `PEP 484`_、`PEP 526`_ 和 `typing`_。
+
+除了 Python 内置的类型，下面还出现了如下 NoneBot 自定类型，实际上它们是 Python 内置类型的别名。
+
+以下类型均可从 nonebot.typing 模块导入。
+
+.. _PEP 484:
+    https://www.python.org/dev/peps/pep-0484/
+
+.. _PEP 526:
+    https://www.python.org/dev/peps/pep-0526/
+
+.. _typing:
+    https://docs.python.org/3/library/typing.html
+"""
 
 from types import ModuleType
 from typing import NoReturn, TYPE_CHECKING
@@ -26,15 +45,64 @@ def overrides(InterfaceClass: object):
 
 
 Driver = TypeVar("Driver", bound="BaseDriver")
+"""
+:类型: `BaseDriver`
+
+:说明:
+
+  所有 Driver 的基类。
+"""
 WebSocket = TypeVar("WebSocket", bound="BaseWebSocket")
+"""
+:类型: `BaseWebSocket`
+
+:说明:
+
+  所有 WebSocket 的基类。
+"""
 
 Bot = TypeVar("Bot", bound="BaseBot")
+"""
+:类型: `BaseBot`
+
+:说明:
+
+  所有 Bot 的基类。
+"""
 Event = TypeVar("Event", bound="BaseEvent")
+"""
+:类型: `BaseEvent`
+
+:说明:
+
+  所有 Event 的基类。
+"""
 Message = TypeVar("Message", bound="BaseMessage")
+"""
+:类型: `BaseMessage`
+
+:说明:
+
+  所有 Message 的基类。
+"""
 MessageSegment = TypeVar("MessageSegment", bound="BaseMessageSegment")
+"""
+:类型: `BaseMessageSegment`
+
+:说明:
+
+  所有 MessageSegment 的基类。
+"""
 
 PreProcessor = Callable[[Bot, Event, dict], Union[Awaitable[None],
                                                   Awaitable[NoReturn]]]
+"""
+:类型: `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]`
+
+:说明:
+
+  消息预处理函数 PreProcessor 类型
+"""
 
 Matcher = TypeVar("Matcher", bound="MatcherClass")
 Handler = Callable[[Bot, Event, dict], Union[Awaitable[None],