docs: 添加开发指南 (#127)

CONTRIBUTING.md

@@ -1,103 +1,5 @@
 # AliceBot 贡献指南
 
-非常感谢您愿意为 AliceBot 项目贡献代码。
+<https://docs.alicebot.dev/develop/contributing>
 
-为了项目代码的质量和一致性，在正式开始您的贡献前，请先阅读本文档并遵循本文档的指引。
-
-## 配置开发环境
-
-### 安装依赖
-
-AliceBot 使用 [PDM](https://pdm.fming.dev/) 管理项目的依赖。
-
-因此，你需要先根据 [PDM](https://pdm-project.org/latest/#installation) 的指引安装 PDM，之后在项目目录中执行以下命令：
-
-```shell
-pdm install
-```
-
-AliceBot 项目的文档使用 [VitePress](https://vitepress.dev/) 生成，如果你想要贡献 AliceBot 的文档，请额外安装 [pnpm](https://pnpm.io/) 环境，并在项目目录中执行以下命令：
-
-```shell
-pnpm install
-```
-
-### 编辑器配置
-
-虽然并非强制，但强烈建议你使用 VSCode 作为编辑器对 AliceBot 项目的代码进行编辑，因为 AliceBot 具有完全的类型注解，VSCode 的 Pylance 插件具有相对较好的静态类型检查效果。
-
-如果你使用 VSCode 作为编辑器，需要安装 **Python**、**Pylance** 和 **Ruff** 插件，并进行以下配置：
-
-```json
-{
-  "[python]": {
-    "editor.formatOnPaste": false,
-    "editor.formatOnSaveMode": "file",
-    "editor.defaultFormatter": "charliermarsh.ruff"
-  }
-}
-```
-
-## 代码规范
-
-### 代码质量
-
-请确保你的代码风格和项目现有代码保持一致，变量命名清晰且符合规范，有适量的注释与测试代码，不要破坏现有功能。
-
-### 代码风格
-
-AliceBot 的代码风格遵循 [PEP 8](https://www.python.org/dev/peps/pep-0008/) 规范。
-
-AliceBot 使用 [Ruff](https://docs.astral.sh/ruff/) 作为格式化工具，如果你已经按照上文配置了 VSCode，那么你应该很容易遵循此规范，否则请在提交前手动执行上述格式化工具。
-
-### 类型注解
-
-AliceBot 具有完全的类型注解。
-
-在 [pyproject.toml](./pyproject.toml) 文件中已经提供了针对 Pyright (Pylance 背后的类型检查器) 的配置，请确保你的代码能够通过这种严格程度的类型检查。
-
-如果必要，你可以在代码中使用 `# type: ignore` 注释来抑制类型检查，但请注意，请将此作为最后手段，不要轻易使用。
-
-### Docstring
-
-AliceBot 中的全部函数、类、模块都具有 Docstring，AliceBot 的 Docstring 遵循 [Google 风格](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)，但请注意不需要在 Docstring 中添加类型。
-
-```python
-def foo(a: int, b: float) -> str:
-    """错误的 Docstring。
-
-    Args:
-        a (int): 参数 a 的说明。
-        b (float): 参数 b 的说明。
-
-    Returns:
-        str: 返回值的说明。
-    """
-
-def foo(a: int, b: float) -> str:
-    """正确的 Docstring。
-
-    Args:
-        a: 参数 a 的说明。
-        b: 参数 b 的说明。
-
-    Returns:
-        返回值的说明。
-    """
-```
-
-## 贡献文档
-
-AliceBot 使用使用 [VitePress](https://vitepress.dev/) 生成文档。API 文档则由 [Sophia-doc](https://github.com/st1020/sophia-doc) 自动生成。
-
-在你修改完 AliceBot 的文档后，可以使用 pnpm 安装依赖后在开发模式下实时预览文档：
-
-```shell
-pnpm run docs:dev
-```
-
-## Commit 规范
-
-请尽量使你的每一个 commit 都只做一件事。
-
-AliceBot 的 commit message 格式遵循 [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) 规范。
+<https://github.com/AliceBotProject/alicebot/blob/master/docs/develop/contributing.md>

docs/.vitepress/config.ts

@@ -34,13 +34,15 @@ export default defineConfig({
     nav: [
       { text: '主页', link: '/' },
       { text: '指南', link: '/guide/', activeMatch: '/guide/' },
+      { text: '开发', link: '/develop/plugin', activeMatch: '/develop/' },
       { text: 'API', link: '/api/', activeMatch: '/api/' },
       { text: '商店', link: '/store/' },
       { text: '更新日志', link: '/changelog' },
     ],
 
     sidebar: {
       '/guide/': sidebarGuide(),
+      '/develop/': sidebarDevelop(),
       '/api/': sidebarApi('/api/'),
       '/dev-api/': sidebarApi('/dev-api/'),
     },
@@ -154,6 +156,19 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
   ]
 }
 
+function sidebarDevelop(): DefaultTheme.SidebarItem[] {
+  return [
+    {
+      text: '开发者指南',
+      collapsed: false,
+      items: [
+        '/develop/plugin.md',
+        '/develop/contributing.md',
+      ].map(getSidebarItem),
+    },
+  ]
+}
+
 function sidebarApi(base: string): DefaultTheme.SidebarItem[] {
   return [
     {

docs/develop/contributing.md

@@ -0,0 +1,107 @@
+# 贡献指南
+
+::: tip 注意
+本文档适用于希望为 AliceBot 本身做出贡献的开发者。
+:::
+
+非常感谢您愿意为 AliceBot 项目贡献代码。
+
+为了项目代码的质量和一致性，在正式开始您的贡献前，请先阅读本文档并遵循本文档的指引。
+
+## 配置开发环境
+
+### 安装依赖
+
+AliceBot 使用 [PDM](https://pdm.fming.dev/) 管理项目的依赖。
+
+因此，你需要先根据 [PDM](https://pdm-project.org/latest/#installation) 的指引安装 PDM，之后在项目目录中执行以下命令：
+
+```shell
+pdm install
+```
+
+AliceBot 项目的文档使用 [VitePress](https://vitepress.dev/) 生成，如果你想要贡献 AliceBot 的文档，请额外安装 [pnpm](https://pnpm.io/)，并在项目目录中执行以下命令：
+
+```shell
+pnpm install
+```
+
+### 编辑器配置
+
+虽然并非强制，但建议使用 VSCode 作为编辑器对 AliceBot 项目的代码进行编辑，因为 AliceBot 具有完全的类型注解，VSCode 的 Pylance 插件具有相对较好的静态类型检查效果。
+
+如果你使用 VSCode 作为编辑器，需要安装 **Python**、**Pylance** 和 **Ruff** 插件，并进行以下配置：
+
+```json
+{
+  "[python]": {
+    "editor.formatOnPaste": false,
+    "editor.formatOnSaveMode": "file",
+    "editor.defaultFormatter": "charliermarsh.ruff"
+  }
+}
+```
+
+## 代码规范
+
+### 代码质量
+
+请确保你的代码风格和项目现有代码保持一致，变量命名清晰且符合规范，有适量的注释与测试代码，不要破坏现有功能。
+
+### 代码风格
+
+AliceBot 的代码风格遵循 [PEP 8](https://www.python.org/dev/peps/pep-0008/) 规范。
+
+AliceBot 使用 [Ruff](https://docs.astral.sh/ruff/) 作为格式化工具，如果你已经按照上文配置了 VSCode，那么你应该很容易遵循此规范，否则请在提交前手动执行上述格式化工具。
+
+### 类型注解
+
+AliceBot 具有完全的类型注解。
+
+在 [pyproject.toml](https://github.com/AliceBotProject/alicebot/blob/master/pyproject.toml) 文件中已经提供了针对 Pyright (Pylance 背后的类型检查器) 和 MyPy 的配置，请确保你的代码能够通过这种严格程度的类型检查。
+
+如果必要，你可以在代码中使用 `# type: ignore` 注释来抑制类型检查，但请注意，请将此作为最后手段，不要轻易使用。
+
+### Docstring
+
+AliceBot 中的全部函数、类、模块都具有 Docstring，AliceBot 的 Docstring 遵循 [Google 风格](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)，但请注意不需要在 Docstring 中添加类型。
+
+```python
+def foo(a: int, b: float) -> str:
+    """错误的 Docstring。
+
+    Args:
+        a (int): 参数 a 的说明。
+        b (float): 参数 b 的说明。
+
+    Returns:
+        str: 返回值的说明。
+    """
+
+def foo(a: int, b: float) -> str:
+    """正确的 Docstring。
+
+    Args:
+        a: 参数 a 的说明。
+        b: 参数 b 的说明。
+
+    Returns:
+        返回值的说明。
+    """
+```
+
+## 贡献文档
+
+AliceBot 使用使用 [VitePress](https://vitepress.dev/) 生成文档。API 文档则由 [Sophia-doc](https://github.com/st1020/sophia-doc) 自动生成。
+
+在你修改完 AliceBot 的文档后，可以使用 pnpm 安装依赖后在开发模式下实时预览文档：
+
+```shell
+pnpm run docs:dev
+```
+
+## Commit 规范
+
+请尽量使你的每一个 commit 都只做一件事。
+
+AliceBot 的 commit message 格式遵循 [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) 规范。

docs/develop/plugin.md

@@ -0,0 +1,77 @@
+# 发布插件
+
+AliceBot 提供了一个商店，用于分享用户开发的插件。当你已经完成了自己的插件开发，并且希望将他分享给大家，那么本篇教程将会帮助你完成。
+
+在阅读本插件开发指南前，请先确保你已经阅读了[指南](/guide/)中关于如何插件开发的部分，并且已经可以顺利开发一个自己的插件。
+
+## 插件模板
+
+AliceBot 提供了一个插件模版 [AliceBotProject/alicebot-plugin-template](https://github.com/AliceBotProject/alicebot-plugin-template)，为了避免不必要的麻烦，建议直接从插件模块开始你的插件。
+
+```sh
+git clone https://github.com/AliceBotProject/alicebot-plugin-template.git
+```
+
+### 开始
+
+AliceBot 的插件的项目名建议以 `alicebot-plugin-` 开头，全部小写，例如 `alicebot-plugin-example`。项目名应该被用于 PyPI 的包名、代码仓库名等。对于模块名，则应按照 Python 语言的惯例，将项目名中的 `-` 替换为 `_`，例如 `alicebot_plugin_example`。
+
+例如，我们将开发一个名为 `alicebot-plugin-hello` 的插件。
+
+首先，修改 clone 下来的模版的目录名为 `alicebot-plugin-hello`，并修改其中的 `alicebot_plugin_template` 目录的目录名为 `alicebot_plugin_hello`。
+
+编辑 `pyproject.toml` 文件，修改其中有 `# TODO` 注释的部分，将其修改为你的插件的对应信息。比如，现在我们需要将 `project.name` 从 `alicebot-plugin-template` 修改为 `alicebot-plugin-hello`。
+
+```toml {2}
+[project]
+name = "alicebot-plugin-hello" # TODO
+version = "0.1.0" # TODO
+description = "AliceBot Plugin Template." # TODO
+authors = [{ name = "AliceBot", email = "[email protected]" }] # TODO
+license = { text = "MIT" } # TODO
+
+# ...
+```
+
+之后编辑 `README.md` 文件和 `LICENSE` 文件，将其替换为你的插件的对应信息。
+
+### 编写插件
+
+AliceBot 插件模版使用 [PDM](https://pdm-project.org/) 作为依赖管理工具，因此，你需要先根据 [PDM](https://pdm-project.org/latest/#installation) 的指引安装 PDM，之后在项目目录中执行以下命令：
+
+```sh
+pdm install
+```
+
+如果你的插件依赖了其他包，可以使用以下命令添加依赖：
+
+```sh
+pdm add <package>
+```
+
+你的插件的代码应位于 `alicebot_plugin_<you_plugin_name>` 目录下，插件模板提供了一个简单的插件示例，你可以在此基础上进行修改。
+
+### 发布插件
+
+为了将你的插件提交到 AliceBot 的插件商店，你需要先将你的插件发布到 PyPI 上。
+
+在上传之前，你应该首先检查：
+
+1. 确保你的插件已经可以正常安装，并且可以运行。
+2. 确保的你插件的信息无误，`pyproject.toml` 文件中的信息已经正确填写，`README.md` 文件和 `LICENSE` 文件已经替换为你自己的信息。
+
+你可以参考 [PyPI 文档](https://packaging.python.org/en/latest/tutorials/packaging-projects/#uploading-the-distribution-archives)和 [PDM 文档](https://pdm-project.org/latest/usage/publish/)的指引将你的插件发布到 PyPI 上。
+
+简单来说，你需要注册一个 PyPI 账号，生成一个个人访问令牌 (Token)，最后使用 `pdm publish` 命令将你的插件发布到 PyPI 上。
+
+完成 PyPI 的发布后就可以将你的插件发布在 AliceBot 的插件商店了。
+
+你可以点击以下链接在 [AliceBotProject/alicebot-store](https://github.com/AliceBotProject/alicebot-store) 仓库新建一个 Issue：
+
+<https://github.com/AliceBotProject/alicebot-store/issues/new/choose>
+
+选择“Publish a plugin”，修改 Issue 的标题中的 `{name}` 为你的插件的名字，并在下方的表单中填写 `pypi_name` 和 `module_name`。
+
+比如，对于之前提到的 `alicebot-plugin-hello` 这个插件来说，Issue 的标题应该是 `[plugin]: Hello`，`pypi_name` 应该填写 `alicebot-plugin-hello`，`module_name` 应该填写 `alicebot_plugin_hello`。
+
+提交 Issue 后，机器人将开始自动验证，通过验证后将自动提交 PR，你只需要等待管理员合并 PR 即可将插件发布在 AliceBot 的插件商店。