更新文档

docs/source/function/utils/cache.rst

@@ -1,7 +1,7 @@
 :mod:`cache` -- 应用缓存模块
 ================================
 
-:mod:`cache` 模块源代码在文件夹 `applications/common/utils/cache.py` 下，主要用于简单的程序数据缓存。
+:mod:`cache` 模块源代码在文件 `applications/common/utils/cache.py` 下，主要用于简单的程序数据缓存。
 
 目前此模块仅启用应用程序缓存，暂时没有联动 Redis 等数据库缓存的功能，后续有意向添加。您可以在自己的项目中添加相关的函数，当然也非常欢迎提交 PR ，一起完善项目。
 

docs/source/function/utils/captcha.rst

@@ -1,7 +1,7 @@
 :mod:`captcha` -- 验证码生成模块
 ==================================
 
-:mod:`captcha` 模块源代码在文件夹 `applications/common/utils/captcha.py` 下，主要用于生成验证码图片。
+:mod:`captcha` 模块源代码在文件 `applications/common/utils/captcha.py` 下，主要用于生成验证码图片。
 
 .. module:: captcha
 

docs/source/function/utils/http.rst

@@ -1,7 +1,9 @@
+.. _JSON 响应正文生成模块:
+
 :mod:`http` -- JSON 响应正文生成模块
 =======================================
 
-:mod:`http` 模块源代码在文件夹 `applications/common/utils/http.py` 下，主要用于生成 JSON 格式的响应正文。
+:mod:`http` 模块源代码在文件 `applications/common/utils/http.py` 下，主要用于生成 JSON 格式的响应正文。
 
 对于大部分 JSON 格式响应的数据，请尽量遵循响应格式规范。如此方便后续前后端的分离和项目的构建。
 
@@ -36,4 +38,22 @@
     :param limit: 每页数据条数，默认为 10。
     :return: 返回 JSON 格式的响应，包含 `msg`、`code`、`data`、`count` 和 `limit` 字段。
 
+**示例：**
 
+.. code-block:: python
+
+    from applications.common.utils.http import success_api, fail_api
+
+    @bp.get('/init')
+    def init():
+        if ...:
+            return success_api(msg="初始化成功")
+        return fail_api(msg="初始化失败")
+
+.. code-block:: python
+
+    from applications.common.utils.http import table_api
+
+    @bp.get('/data')
+    def data():
+        return table_api(data=[], total=0)

docs/source/function/utils/index.rst

@@ -3,7 +3,7 @@
 目录索引
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
 
     cache
     captcha

docs/source/function/utils/mail.rst

@@ -1,7 +1,11 @@
+.. _邮件模块:
+
 :mod:`mail` -- 邮件模块
 ==================================
 
-:mod:`mail` 模块源代码在文件夹 `applications/common/utils/mail.py` 下，主要用于邮件的发送。
+:mod:`mail` 模块源代码在文件 `applications/common/utils/mail.py` 下，主要用于邮件的发送。
+
+使用前，需要正确在 `applications/config.py` 中配置 SMTP 服务器。
 
 .. module:: mail
 
@@ -31,14 +35,23 @@
 
 .. function:: add(receiver, subject, content, user_id)
 
-   发送一封邮件，并将发送记录保存到数据库。 **该方法被邮件发送的视图函数调用。**
+    发送一封邮件，并将发送记录保存到数据库。 **该方法被邮件发送的视图函数调用。**
 
-   :param receiver: 接收者邮箱地址，多个邮箱用英文分号隔开。
-   :param subject: 邮件主题。
-   :param content: 邮件内容（HTML 格式）。
-   :param user_id: 发送者用户ID，表示谁发送了这封邮件。
+    :param receiver: 接收者邮箱地址，多个邮箱用英文分号隔开。
+    :param subject: 邮件主题。
+    :param content: 邮件内容（HTML 格式）。
+    :param user_id: 发送者用户ID，表示谁发送了这封邮件。
                   可以使用 `from flask_login import current_user; current_user.id` 获取当前登录用户的ID。
-   :return: 发送成功返回 True，失败报错。
+    :return: 发送成功返回 True，失败报错。
+
+    **示例**
+
+    .. code-block:: python
+
+        from flask_login import current_user
+        from applications.common.utils import mail
+
+        mail.add("test@test.com", "subject", "<h1>Hello</h1>", current_user.id)
 
 
 .. function:: delete(id)

docs/source/function/utils/rights.rst

@@ -1,7 +1,9 @@
+.. _权限验证模块:
+
 :mod:`rights` -- 权限验证模块
 ==================================
 
-:mod:`rights` 模块源代码在文件夹 `applications/common/utils/rights.py` 下，主要用于权限验证。
+:mod:`rights` 模块源代码在文件 `applications/common/utils/rights.py` 下，主要用于权限验证。
 
 .. module:: rights
 
@@ -23,6 +25,8 @@
 
     .. code-block:: python
 
+        from applications.common.utils.rights import authorize
+
         @app.route("/test")
         @authorize("system:power:remove", log=True)
         def test_index():

docs/source/function/utils/upload.rst

@@ -1,7 +1,7 @@
 :mod:`upload` -- 文件上传模块
 ==================================
 
-:mod:`upload` 模块源代码在文件夹 `applications/common/utils/upload.py` 下，主要用于文件上传，目前主要用于图片上传。
+:mod:`upload` 模块源代码在文件 `applications/common/utils/upload.py` 下，主要用于文件上传，目前主要用于图片上传。
 
 .. module:: upload
 

docs/source/function/utils/validate.rst

@@ -1,7 +1,7 @@
 :mod:`validate` -- 效验模块
 ==================================
 
-:mod:`validate` 模块源代码在文件夹 `applications/common/utils/validate.py` 下，主要用于数据效验与过滤。
+:mod:`validate` 模块源代码在文件 `applications/common/utils/validate.py` 下，主要用于数据效验与过滤。
 
 .. module:: validate