📝 archive docs

archive/2.0.0a10/advanced/README.md

@@ -0,0 +1,7 @@
+# 深入
+
+## 它如何工作？
+
+<!-- TODO: how to work -->
+
+~~未填坑~~

archive/2.0.0a10/advanced/export-and-require.md

@@ -0,0 +1,117 @@
+# 跨插件访问
+
+由于 `nonebot2` 独特的插件加载机制，在使用 python 原有的 import 机制来进行插件之间的访问时，很可能会有奇怪的或者意料以外的情况发生。为了避免这种情况的发生，您可以有两种方法来实现跨插件访问：
+
+1. 将插件间的要使用的公共代码剥离出来，作为公共文件或者文件夹，提供给插件加以调用。
+2. 使用 `nonebot2` 提供的 `export` 和 `require` 机制，来实现插件间的互相调用。
+
+第一种方法比较容易理解和实现，这里不再赘述，但需要注意的是，请不要将公共文件或者公共文件夹作为**插件**被 `nonebot2` 加载。
+
+下面将介绍第二种方法—— `export` 和 `require` 机制：
+
+## 使用 export and require
+
+现在，假定有两个插件 `pluginA` 和 `pluginB`，需要在 `pluginB` 中调用 `pluginA` 中的一个变量 `varA` 和一个函数 `funcA`。
+
+在上面的条件中涉及到了两种操作：一种是在 `pluginA` 的 `导出对象` 操作；而另一种是在 `pluginB` 的 `导入对象` 操作。在 `nonebot2` 中，`导出对象` 的操作用 `export` 机制来实现，`导入对象` 的操作用 `require` 机制来实现。下面，我们将逐一进行介绍。
+
+:::warning 警告
+
+使用这个方法进行跨插件访问时，**需要先加载`导出对象`的插件，再加载`导入对象`的插件。**
+
+:::
+
+### 使用 export
+
+在 `pluginA` 中，我们调用 `export` 机制 `导出对象`。
+
+在 `export` 机制调用前，我们需要保证导出的对象已经被定义，比如：
+
+```python
+varA = "varA"
+
+
+def funcA():
+    return "funcA"
+```
+
+在确保定义之后，我们可以从 `nonebot.plugin` 导入 `export()` 方法, `export()` 方法会返回一个特殊的字典 `export`：
+
+```python
+from nonebot.plugin import export
+
+export=export()
+```
+
+这个字典可以用来装载导出的对象，它的 key 是对象导出后的命名，value 是对象本身，我们可以直接创建新的 `key` - `value` 对导出对象：
+
+```python
+export.vA = varA
+export.fA = funcA
+```
+
+除此之外，也支持 `嵌套` 导出对象：
+
+```python
+export.sub.vA = varA
+export.sub.fA = funcA
+```
+
+特别地，对于 `函数对象` 而言，`export` 支持用 `装饰器` 的方法来导出，因此，我们可以这样定义 `funcA`：
+
+```python
+@export.sub
+def funcA():
+    return "funcA"
+```
+
+或者:
+
+```python
+@export
+def funcA():
+    return "funcA"
+```
+
+通过 `装饰器` 的方法导出函数时，命名固定为函数的命名，也就是说，上面的两个例子等同于：
+
+```python
+export.sub.funcA = funcA
+
+export.funcA = funcA
+```
+
+这样，我们就成功导出 `varA` 和 `funcA` 对象了。
+
+下面我们将介绍如何在 `pluginB` 中导入这些对象。
+
+### 使用 require
+
+在 `pluginB` 中，我们调用 `require` 机制 `导入对象`。
+
+:::warning 警告
+
+在导入来自其他插件的对象时, 请确保导出该对象的插件在引用该对象的插件之前加载。如果该插件并未被加载，则会尝试加载，加载失败则会返回 `None`。
+
+:::
+
+我们可以从 `nonebot.plugin` 中导入 `require()` 方法：
+
+```python
+from nonebot.plugin import require
+```
+
+`require()` 方法的参数是插件名, 它会返回在指定插件中，用 `export()` 方法创建的字典。
+
+```python
+require_A = require('pluginA')
+```
+
+在之前，这个字典已经存入了 `'vA'` - `varA`, `'fA'` - `funcA` 或 `'funcA'` - `funcA` 这样的 `key` - `value` 对。因此在这里我们直接用 `属性` 的方法来获取导入对象:
+
+```python
+varA = require_A.vA
+funcA = require_A.fA or require_A.funcA
+```
+
+这样，我们就在 `pluginB` 中成功导入了 `varA` 和 `funcA` 对象了。

archive/2.0.0a10/advanced/overloaded-handlers.md

@@ -0,0 +1 @@
+# 事件处理函数重载

archive/2.0.0a10/advanced/permission.md

@@ -0,0 +1 @@
+# 权限控制

archive/2.0.0a10/advanced/publish-plugin.md

@@ -0,0 +1 @@
+# 发布插件

archive/2.0.0a10/advanced/runtime-hook.md

@@ -0,0 +1 @@
+# 钩子函数

archive/2.0.0a10/advanced/scheduler.md

@@ -0,0 +1,135 @@
+# 定时任务
+
+[`APScheduler`](https://apscheduler.readthedocs.io/en/latest/index.html) —— Advanced Python Scheduler
+
+> Advanced Python Scheduler (APScheduler) is a Python library that lets you schedule your Python code to be executed later, either just once or periodically. You can add new jobs or remove old ones on the fly as you please. If you store your jobs in a database, they will also survive scheduler restarts and maintain their state. When the scheduler is restarted, it will then run all the jobs it should have run while it was offline.
+
+## 从 NoneBot v1 迁移
+
+`APScheduler` 作为 `nonebot` v1 的可选依赖，为众多 bot 提供了方便的定时任务功能。`nonebot2` 已将 `APScheduler` 独立为 `nonebot_plugin_apscheduler` 插件，你可以在 [插件广场](https://v2.nonebot.dev/plugin-store.html) 中找到它。
+
+相比于 `nonebot` v1 ，只需要安装插件并修改 `scheduler` 的导入方式即可完成迁移。
+
+## 安装插件
+
+### 通过 nb-cli
+
+如正在使用 `nb-cli` 构建项目，你可以从插件市场复制安装命令或手动输入以下命令以添加 `nonebot_plugin_apscheduler`。
+
+```bash
+nb plugin install nonebot_plugin_apscheduler
+```
+
+:::tip 提示
+`nb-cli` 默认通过 `pypi` 安装，你可以添加命令参数 `-i [mirror]` 或 `--index [mirror]` 以使用镜像源安装。
+:::
+
+### 通过 poetry
+
+执行以下命令以添加 `nonebot_plugin_apscheduler`
+
+```bash
+poetry add nonebot-plugin-apscheduler
+```
+
+:::tip 提示
+由于稍后我们将使用 `nonebot.require()` 方法进行导入，所以无需额外的 `nonebot.load_plugin()`
+:::
+
+## 快速上手
+
+1. 在需要设置定时任务的插件中，通过 `nonebot.require` 从 `nonebot_plugin_apscheduler` 导入 `scheduler` 对象
+
+2. 在该对象的基础上，根据 `APScheduler` 的使用方法进一步配置定时任务
+
+将上述步骤归纳为最小实现的代码如下：
+
+```python
+from nonebot import require
+
+scheduler = require('nonebot_plugin_apscheduler').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")
+```
+
+## 分步进行
+
+### 导入 scheduler 对象
+
+为了使插件能够实现定时任务，需要先将 `scheduler` 对象导入插件。
+
+`nonebot2` 提供了 `nonebot.require` 方法来实现导入其他插件的内容，此处我们使用这个方法来导入 `scheduler` 对象。
+
+`nonebot` 使用的 `scheduler` 对象为 `AsyncScheduler` 。
+
+> 使用该方法传入的插件本身也需要有对应实现，关于该方法的更多介绍可以参阅 [这里](./export-and-require.md)
+
+```python
+from nonebot import require
+
+scheduler = require('nonebot_plugin_apscheduler').scheduler
+```
+
+### 编写定时任务
+
+由于本部分为标准的通过 `APScheduler` 配置定时任务，有关指南请参阅 [APScheduler 官方文档](https://apscheduler.readthedocs.io/en/latest/userguide.html#adding-jobs)。
+
+### 配置插件选项
+
+根据项目的 `.env` 文件设置，向 `.env.*` 或 `bot.py` 文件添加 `nonebot_plugin_apscheduler` 的可选配置项
+
+:::warning 注意
+`.env.*` 文件的编写应遵循 nonebot2 对 `.env.*` 文件的编写要求
+:::
+
+#### `apscheduler_autostart`
+
+类型：`bool`
+
+默认值：`True`
+
+是否自动启动 `APScheduler`。
+
+对于大多数情况，我们需要在 `nonebot2` 项目被启动时启动定时任务，则此处设为 `true`
+
+##### 在 `.env` 中添加
+
+```bash
+APSCHEDULER_AUTOSTART=true
+```
+
+##### 在 `bot.py` 中添加
+
+```python
+nonebot.init(apscheduler_autostart=True)
+```
+
+#### `apscheduler_config`
+
+类型：`dict`
+
+默认值：`{"apscheduler.timezone": "Asia/Shanghai"}`
+
+`APScheduler` 相关配置。修改/增加其中配置项需要确保 `prefix: apscheduler`。
+
+对于 `APScheduler` 的相关配置，请参阅 [scheduler-config](https://apscheduler.readthedocs.io/en/latest/userguide.html#scheduler-config) 和 [BaseScheduler](https://apscheduler.readthedocs.io/en/latest/modules/schedulers/base.html#apscheduler.schedulers.base.BaseScheduler)
+
+> 官方文档在绝大多数时候能提供最准确和最具时效性的指南
+
+##### 在 `.env` 中添加
+
+```bash
+APSCHEDULER_CONFIG={"apscheduler.timezone": "Asia/Shanghai"}
+```
+
+##### 在 `bot.py` 中添加
+
+```python
+nonebot.init(apscheduler_config={
+    "apscheduler.timezone": "Asia/Shanghai"
+})
+```