From 1febb251193718a530a284eb18e9898c1c2fec2f Mon Sep 17 00:00:00 2001 From: Stone Date: Sun, 16 Jun 2024 22:39:54 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=BC=80=E5=8F=91?= =?UTF-8?q?=E6=8C=87=E5=8D=97=20(#127)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 102 +-------------------------------- docs/.vitepress/config.ts | 15 +++++ docs/develop/contributing.md | 107 +++++++++++++++++++++++++++++++++++ docs/develop/plugin.md | 77 +++++++++++++++++++++++++ 4 files changed, 201 insertions(+), 100 deletions(-) create mode 100644 docs/develop/contributing.md create mode 100644 docs/develop/plugin.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cfbf45b..5b81d30 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,103 +1,5 @@ # 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](./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/) 规范。 + diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 10e8b32..7e3d6bd 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -34,6 +34,7 @@ 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' }, @@ -41,6 +42,7 @@ export default defineConfig({ 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 [ { diff --git a/docs/develop/contributing.md b/docs/develop/contributing.md new file mode 100644 index 0000000..8b44775 --- /dev/null +++ b/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/) 规范。 diff --git a/docs/develop/plugin.md b/docs/develop/plugin.md new file mode 100644 index 0000000..af7e77b --- /dev/null +++ b/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 = "concontact@alicebot.dev" }] # 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 +``` + +你的插件的代码应位于 `alicebot_plugin_` 目录下，插件模板提供了一个简单的插件示例，你可以在此基础上进行修改。 + +### 发布插件 + +为了将你的插件提交到 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： + + + +选择“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 的插件商店。