From 5e3d1c76cca4d60e8eaa4781d6c7479269e59e75 Mon Sep 17 00:00:00 2001
From: yanyongyu <yanyongyu_1@126.com>
Date: Wed, 19 Aug 2020 20:29:37 +0800
Subject: [PATCH] add nonebot.typing docs

---
 docs/api/README.md     |  13 +++
 docs/api/config.md     |  32 +++++++
 docs/api/nonebot.md    | 203 +++++++++++++++++++++++++++++++++++++++++
 docs/api/typing.md     | 128 ++++++++++++++++++++++++++
 docs_build/conf.py     |  10 +-
 docs_build/config.rst  |   6 ++
 docs_build/nonebot.rst |   1 -
 docs_build/typing.rst  |   6 ++
 nonebot/__init__.py    |  50 +++++-----
 nonebot/typing.py      |  68 ++++++++++++++
 poetry.lock            |   3 +-
 11 files changed, 486 insertions(+), 34 deletions(-)
 create mode 100644 docs/api/README.md
 create mode 100644 docs/api/config.md
 create mode 100644 docs/api/nonebot.md
 create mode 100644 docs/api/typing.md
 create mode 100644 docs_build/config.rst
 create mode 100644 docs_build/typing.rst

diff --git a/docs/api/README.md b/docs/api/README.md
new file mode 100644
index 00000000..c9dd2074
--- /dev/null
+++ b/docs/api/README.md
@@ -0,0 +1,13 @@
+# NoneBot Api Reference
+
+
+* **模块索引**
+
+    
+    * [nonebot](nonebot.html)
+
+
+    * [nonebot.typing](typing.html)
+
+
+    * [nonebot.config](config.html)
diff --git a/docs/api/config.md b/docs/api/config.md
new file mode 100644
index 00000000..6f450715
--- /dev/null
+++ b/docs/api/config.md
@@ -0,0 +1,32 @@
+# NoneBot.config 模块
+
+
+### _class_ `BaseConfig(_env_file='<objectobject>', _env_file_encoding=None)`
+
+基类：`pydantic.env_settings.BaseSettings`
+
+
+### _class_ `Config(_env_file='<objectobject>', _env_file_encoding=None, *, driver='nonebot.drivers.fastapi', host=IPv4Address('127.0.0.1'), port=8080, secret=None, debug=False, api_root={}, api_timeout=60.0, access_token=None, superusers={}, nickname='', command_start={'/'}, command_sep={'.'}, session_expire_timeout=datetime.timedelta(seconds=120), **values)`
+
+基类：[`nonebot.config.BaseConfig`](#nonebot.config.BaseConfig)
+
+NoneBot Config Object
+
+configs:
+
+### driver
+
+
+* 类型: str
+
+
+* 默认值: "nonebot.drivers.fastapi"
+
+
+* 说明:
+nonebot 运行使用后端框架封装 Driver 。继承自 nonebot.driver.BaseDriver 。
+
+
+### _class_ `Env(_env_file='<objectobject>', _env_file_encoding=None, *, environment='prod')`
+
+基类：`pydantic.env_settings.BaseSettings`
diff --git a/docs/api/nonebot.md b/docs/api/nonebot.md
new file mode 100644
index 00000000..0d69f010
--- /dev/null
+++ b/docs/api/nonebot.md
@@ -0,0 +1,203 @@
+# NoneBot 模块
+
+
+### `get_app()`
+
+
+* **说明**
+
+    获取全局 Driver 对应 Server App 对象。
+
+
+
+* **返回**
+
+    
+    * `Any`: Server App 对象
+
+
+
+* **异常**
+
+    
+    * `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
+
+
+
+* **用法**
+
+
+```python
+app = nonebot.get_app()
+```
+
+
+### `get_asgi()`
+
+
+* **说明**
+
+    获取全局 Driver 对应 Asgi 对象。
+
+
+
+* **返回**
+
+    
+    * `Any`: Asgi 对象
+
+
+
+* **异常**
+
+    
+    * `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
+
+
+
+* **用法**
+
+
+```python
+asgi = nonebot.get_asgi()
+```
+
+
+### `get_bots()`
+
+
+* **说明**
+
+    获取所有通过 ws 连接 NoneBot 的 Bot 对象。
+
+
+
+* **返回**
+
+    
+    * `Dict[str, Bot]`: 一个以字符串 ID 为键，Bot 对象为值的字典
+
+
+
+* **异常**
+
+    
+    * `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
+
+
+
+* **用法**
+
+
+```python
+bots = nonebot.get_bots()
+```
+
+
+### `get_driver()`
+
+
+* **说明**
+
+    获取全局 Driver 对象。可用于在计划任务的回调中获取当前 Driver 对象。
+
+
+
+* **返回**
+
+    
+    * `Driver`: 全局 Driver 对象
+
+
+
+* **异常**
+
+    
+    * `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
+
+
+
+* **用法**
+
+
+```python
+driver = nonebot.get_driver()
+```
+
+
+### `init(*, _env_file=None, **kwargs)`
+
+
+* **说明**
+
+    初始化 NoneBot 以及 全局 Driver 对象。
+
+    NoneBot 将会从 .env 文件中读取环境信息，并使用相应的 env 文件配置。
+
+    你也可以传入自定义的 _env_file 来指定 NoneBot 从该文件读取配置。
+
+
+
+* **参数**
+
+    
+    * `_env_file: Optional[str]`: 配置文件名，默认从 .env.{env_name} 中读取配置
+
+
+    * `**kwargs`: 任意变量，将会存储到 Config 对象里
+
+
+
+* **返回**
+
+    
+    * None
+
+
+
+* **用法**
+
+
+```python
+nonebot.init(database=Database(...))
+```
+
+
+### `run(host=None, port=None, *args, **kwargs)`
+
+
+* **说明**
+
+    启动 NoneBot，即运行全局 Driver 对象。
+
+
+
+* **参数**
+
+    
+    * `host: Optional[str]`: 主机名／IP，若不传入则使用配置文件中指定的值
+
+
+    * `port: Optional[int]`: 端口，若不传入则使用配置文件中指定的值
+
+
+    * `*args`: 传入 Driver.run 的位置参数
+
+
+    * `**kwargs`: 传入 Driver.run 的命名参数
+
+
+
+* **返回**
+
+    
+    * None
+
+
+
+* **用法**
+
+
+```python
+nonebot.run(host="127.0.0.1", port=8080)
+```
diff --git a/docs/api/typing.md b/docs/api/typing.md
new file mode 100644
index 00000000..e9e4987a
--- /dev/null
+++ b/docs/api/typing.md
@@ -0,0 +1,128 @@
+# NoneBot.typing 模块
+
+## 类型
+
+下面的文档中，「类型」部分使用 Python 的 Type Hint 语法，见 [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)。
+
+除了 Python 内置的类型，下面还出现了如下 NoneBot 自定类型，实际上它们是 Python 内置类型的别名。
+
+以下类型均可从 nonebot.typing 模块导入。
+
+
+### `Bot`
+
+
+* **类型**
+
+    BaseBot
+
+
+
+* **说明**
+
+    所有 Bot 的基类。
+
+
+alias of TypeVar('Bot')
+
+
+### `Driver`
+
+
+* **类型**
+
+    BaseDriver
+
+
+
+* **说明**
+
+    所有 Driver 的基类。
+
+
+alias of TypeVar('Driver')
+
+
+### `Event`
+
+
+* **类型**
+
+    BaseEvent
+
+
+
+* **说明**
+
+    所有 Event 的基类。
+
+
+alias of TypeVar('Event')
+
+
+### `Message`
+
+
+* **类型**
+
+    BaseMessage
+
+
+
+* **说明**
+
+    所有 Message 的基类。
+
+
+alias of TypeVar('Message')
+
+
+### `MessageSegment`
+
+
+* **类型**
+
+    BaseMessageSegment
+
+
+
+* **说明**
+
+    所有 MessageSegment 的基类。
+
+
+alias of TypeVar('MessageSegment')
+
+
+### `PreProcessor`
+
+
+* **类型**
+
+    Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]
+
+
+
+* **说明**
+
+    消息预处理函数 PreProcessor 类型
+
+
+alias of Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]
+
+
+### `WebSocket`
+
+
+* **类型**
+
+    BaseWebSocket
+
+
+
+* **说明**
+
+    所有 WebSocket 的基类。
+
+
+alias of TypeVar('WebSocket')
diff --git a/docs_build/conf.py b/docs_build/conf.py
index 252393fc..0afee3b1 100644
--- a/docs_build/conf.py
+++ b/docs_build/conf.py
@@ -10,13 +10,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-import os
-import sys
-# sys.path.insert(
-#     0,
-#     os.path.join(os.path.abspath(os.path.dirname(os.path.dirname(__file__))),
-#                  "nonebot"))
-sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
 
 # -- Project information -----------------------------------------------------
 
diff --git a/docs_build/config.rst b/docs_build/config.rst
new file mode 100644
index 00000000..c34935d8
--- /dev/null
+++ b/docs_build/config.rst
@@ -0,0 +1,6 @@
+NoneBot.config 模块
+===================
+
+.. automodule:: nonebot.config
+   :members:
+   :show-inheritance:
diff --git a/docs_build/nonebot.rst b/docs_build/nonebot.rst
index d1aba847..f921b3a5 100644
--- a/docs_build/nonebot.rst
+++ b/docs_build/nonebot.rst
@@ -3,5 +3,4 @@ NoneBot 模块
 
 .. automodule:: nonebot
    :members:
-   :undoc-members:
    :show-inheritance:
diff --git a/docs_build/typing.rst b/docs_build/typing.rst
new file mode 100644
index 00000000..8b927eaa
--- /dev/null
+++ b/docs_build/typing.rst
@@ -0,0 +1,6 @@
+NoneBot.typing 模块
+===================
+
+.. automodule:: nonebot.typing
+   :members:
+   :show-inheritance:
diff --git a/nonebot/__init__.py b/nonebot/__init__.py
index c996affc..117dda4c 100644
--- a/nonebot/__init__.py
+++ b/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
 
diff --git a/nonebot/typing.py b/nonebot/typing.py
index 74b0345e..78418cf7 100644
--- a/nonebot/typing.py
+++ b/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],
diff --git a/poetry.lock b/poetry.lock
index de883bca..07733deb 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -600,10 +600,9 @@ unify = "*"
 yapf = "*"
 
 [package.source]
-reference = "88a68ed340013067a1c673bdf7541680c581fa60"
+reference = "b7ca9332c2e4c5e50110d6477dd28821c74da778"
 type = "git"
 url = "https://github.com/nonebot/sphinx-markdown-builder.git"
-
 [[package]]
 category = "dev"
 description = "sphinxcontrib-applehelp is a sphinx extension which outputs Apple help books"