From 60c70804ed5c7cd96bc20ff1b74f5b30e944cad2 Mon Sep 17 00:00:00 2001
From: yanyongyu <yanyongyu_1@126.com>
Date: Sun, 13 Sep 2020 00:18:31 +0800
Subject: [PATCH] :bulb: add scheduler docstring

---
 docs/.vuepress/config.js   | 12 +++++++----
 docs/api/README.md         |  8 +++++++-
 docs/api/sched.md          | 41 ++++++++++++++++++++++++++++++++++++++
 docs/guide/installation.md |  2 +-
 docs_build/README.rst      | 10 ++++++----
 docs_build/sched.rst       | 11 ++++++++++
 nonebot/sched.py           | 32 +++++++++++++++++++++++++++++
 7 files changed, 106 insertions(+), 10 deletions(-)
 create mode 100644 docs/api/sched.md
 create mode 100644 docs_build/sched.rst

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 0ef4275e..eb288d04 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -76,6 +76,14 @@ module.exports = context => ({
                   title: "nonebot.typing 模块",
                   path: "typing"
                 },
+                {
+                  title: "nonebot.config 模块",
+                  path: "config"
+                },
+                {
+                  title: "nonebot.sched 模块",
+                  path: "sched"
+                },
                 {
                   title: "nonebot.log 模块",
                   path: "log"
@@ -83,10 +91,6 @@ module.exports = context => ({
                 {
                   title: "nonebot.exception 模块",
                   path: "exception"
-                },
-                {
-                  title: "nonebot.config 模块",
-                  path: "config"
                 }
               ]
             }
diff --git a/docs/api/README.md b/docs/api/README.md
index 1aaf25f7..86282ced 100644
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -10,7 +10,13 @@
     * [nonebot.typing](typing.html)
 
 
+    * [nonebot.config](config.html)
+
+
+    * [nonebot.sched](sched.html)
+
+
     * [nonebot.log](log.html)
 
 
-    * [nonebot.config](config.html)
+    * [nonebot.exception](exception.html)
diff --git a/docs/api/sched.md b/docs/api/sched.md
new file mode 100644
index 00000000..450fd7d0
--- /dev/null
+++ b/docs/api/sched.md
@@ -0,0 +1,41 @@
+---
+contentSidebar: true
+sidebarDepth: 0
+---
+
+# NoneBot.sched 模块
+
+## 计划任务
+
+计划任务使用第三方库 [APScheduler](https://github.com/agronholm/apscheduler) ，使用文档请参考 [APScheduler使用文档](https://apscheduler.readthedocs.io/en/latest/) 。
+
+
+## `scheduler`
+
+
+* **类型**
+
+    `Optional[apscheduler.schedulers.asyncio.AsyncIOScheduler]`
+
+
+
+* **说明**
+
+    当可选依赖 `APScheduler` 未安装时，`scheduler` 为 None
+
+    使用 `pip install nonebot[scheduler]` 安装可选依赖
+
+
+
+* **常用示例**
+
+
+```python
+from nonebot import scheduler
+
+@scheduler.scheduled_job("cron", hour="*/2", id="xxx", args=[1], kwargs={arg2: 2})
+async def run_every_2_hour(arg1, arg2):
+    pass
+
+scheduler.add_job(run_every_day_from_program_start, "interval", days=1, id="xxx")
+```
diff --git a/docs/guide/installation.md b/docs/guide/installation.md
index aaef6600..51dcb5da 100644
--- a/docs/guide/installation.md
+++ b/docs/guide/installation.md
@@ -24,7 +24,7 @@ pip install .
 
 A task scheduling library for Python.
 
-可用于定时任务，后台执行任务等
+可用于计划任务，后台执行任务等
 
 ```bash
 pip install nonebot2[scheduler]
diff --git a/docs_build/README.rst b/docs_build/README.rst
index 1ced2b53..cdcd2844 100644
--- a/docs_build/README.rst
+++ b/docs_build/README.rst
@@ -2,7 +2,9 @@ NoneBot Api Reference
 =====================
 
 :模块索引:
- - `nonebot <nonebot.html>`_
- - `nonebot.typing <typing.html>`_
- - `nonebot.log <log.html>`_
- - `nonebot.config <config.html>`_
+  - `nonebot <nonebot.html>`_
+  - `nonebot.typing <typing.html>`_
+  - `nonebot.config <config.html>`_
+  - `nonebot.sched <sched.html>`_
+  - `nonebot.log <log.html>`_
+  - `nonebot.exception <exception.html>`_
diff --git a/docs_build/sched.rst b/docs_build/sched.rst
new file mode 100644
index 00000000..714be93d
--- /dev/null
+++ b/docs_build/sched.rst
@@ -0,0 +1,11 @@
+---
+contentSidebar: true
+sidebarDepth: 0
+---
+
+NoneBot.sched 模块
+===================
+
+.. automodule:: nonebot.sched
+   :members:
+   :show-inheritance:
diff --git a/nonebot/sched.py b/nonebot/sched.py
index cc54ac1e..58447b67 100644
--- a/nonebot/sched.py
+++ b/nonebot/sched.py
@@ -1,5 +1,16 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+"""
+计划任务
+========
+
+计划任务使用第三方库 `APScheduler`_ ，使用文档请参考 `APScheduler使用文档`_ 。
+
+.. _APScheduler:
+    https://github.com/agronholm/apscheduler
+.. _APScheduler使用文档:
+    https://apscheduler.readthedocs.io/en/latest/
+"""
 
 try:
     from apscheduler.schedulers.asyncio import AsyncIOScheduler
@@ -8,5 +19,26 @@ except ImportError:
 
 if AsyncIOScheduler:
     scheduler = AsyncIOScheduler()
+    """
+    :类型:
+      ``Optional[apscheduler.schedulers.asyncio.AsyncIOScheduler]``
+    :说明:
+      当可选依赖 ``APScheduler`` 未安装时，``scheduler`` 为 None
+
+      使用 ``pip install nonebot[scheduler]`` 安装可选依赖
+
+    :常用示例:
+
+    .. code-block:: python
+
+        from nonebot import scheduler
+
+        @scheduler.scheduled_job("cron", hour="*/2", id="xxx", args=[1], kwargs={arg2: 2})
+        async def run_every_2_hour(arg1, arg2):
+            pass
+
+        scheduler.add_job(run_every_day_from_program_start, "interval", days=1, id="xxx")
+
+    """
 else:
     scheduler = None