ProjectHentai/nonebot2
6
0
Fork 0
mirror of https://github.com/nonebot/nonebot2.git synced 2024-11-24 00:55:07 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

📝 Add style guides for document (#1005)

Browse Source
This commit is contained in:
Jigsaw 2022-05-24 12:36:59 +08:00 committed by GitHub
parent c52637a3b8
commit 558e073cfa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 24 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.markdownlint.yaml Normal file
View File

@ -0,0 +1,4 @@
MD013: false
MD024: # 重复标题
siblings_only: true
MD033: false # 允许 html

29
CONTRIBUTING.md
View File

@ -34,7 +34,7 @@ yarn global add gitmoji-cli
gitmoji -i gitmoji -i
``` ```
### 使用 GitHub Codespaces (Dev Container) ### 使用 GitHub Codespaces（Dev Container）
使用 GitHub Codespaces 选择 `NoneBot2` 项目，然后选择 `.devcontainer/devcontainer.json` 配置即可。 使用 GitHub Codespaces 选择 `NoneBot2` 项目，然后选择 `.devcontainer/devcontainer.json` 配置即可。
@ -44,12 +44,16 @@ gitmoji -i
NoneBot 的 commit message 格式遵循 [gitmoji](https://gitmoji.dev/) 规范，在创建 commit 时请牢记这一点。 NoneBot 的 commit message 格式遵循 [gitmoji](https://gitmoji.dev/) 规范，在创建 commit 时请牢记这一点。
### 工作流概述
`master` 分支为 NoneBot 的开发分支，在任何情况下都请不要直接修改 `master` 分支，而是创建一个目标分支为 `nonebot:master` 的 Pull Request 来提交修改。Pull Request 标题请尽量更改成中文，以便自动生成更新日志。
如果你不是 NoneBot 团队的成员，可在 fork 本仓库后，向本仓库的 `master` 分支发起 Pull Request，注意遵循先前提到的 commit message 规范创建 commit。我们将在 code review 通过后通过 squash merge 方式将您的贡献合并到主分支。
### 撰写文档 ### 撰写文档
NoneBot2 的文档使用 [docusaurus](https://docusaurus.io/)，它有一些 [Markdown 特性](https://docusaurus.io/zh-CN/docs/markdown-features) 可能会帮助到你。 NoneBot2 的文档使用 [docusaurus](https://docusaurus.io/)，它有一些 [Markdown 特性](https://docusaurus.io/zh-CN/docs/markdown-features) 可能会帮助到你。
NoneBot2 文档并没有具体的行文风格规范，但我们建议你尽量写得简单易懂。
如果你需要在本地预览修改后的文档，可以使用 yarn 安装文档依赖后启动 dev server，如下所示： 如果你需要在本地预览修改后的文档，可以使用 yarn 安装文档依赖后启动 dev server，如下所示：
```bash ```bash
@ -57,6 +61,19 @@ yarn install
yarn start yarn start
``` ```
NoneBot2 文档并没有具体的行文风格规范，但我们建议你尽量写得简单易懂。
以下是比较重要的排版规范。目前 NoneBot2 文档中仍有部分文档不完全遵守此规范，如果在阅读时发现欢迎提交 PR。
1. 中文与英文、数字、半角符号之间需要有空格。例：`NoneBot2 是一个可扩展的 Python 异步机器人框架。`
2. 若非英文整句，使用全角标点符号。例：`现在你可以看到机器人回复你：“Hello, World !”。`
3. 直引号`「」`和弯引号`“”`都可接受，但同一份文件里应使用同种引号。
4. **不要使用斜体**，你不需要一种与粗体不同的强调。除此之外，你也可以考虑使用 docusaurus 提供的[告示](https://docusaurus.io/zh-CN/docs/markdown-features/admonitions)功能。
这是社区创始人 richardchien 的中文排版规范，可供参考：<https://stdrc.cc/style-guides/chinese>。
如果你需要编辑器提示 Markdown 规范，可以安装 VSCode 上的 markdownlint 插件。
### 参与开发 ### 参与开发
NoneBot2 的代码风格遵循 [PEP 8](https://www.python.org/dev/peps/pep-0008/) 与 [PEP 484](https://www.python.org/dev/peps/pep-0484/) 规范，请确保你的代码风格和项目已有的代码保持一致，变量命名清晰，有适当的注释与测试代码。 NoneBot2 的代码风格遵循 [PEP 8](https://www.python.org/dev/peps/pep-0008/) 与 [PEP 484](https://www.python.org/dev/peps/pep-0484/) 规范，请确保你的代码风格和项目已有的代码保持一致，变量命名清晰，有适当的注释与测试代码。
@ -70,9 +87,3 @@ NoneBot2 的代码风格遵循 [PEP 8](https://www.python.org/dev/peps/pep-0008/
虽然对插件的内容没有严格限制，但我们还是建议在上架插件之前先查看商店有无功能一致的插件。如果你想要上架商店的插件功能与现有插件不完全重合，请在插件说明中补充其与现有插件的区别。 虽然对插件的内容没有严格限制，但我们还是建议在上架插件之前先查看商店有无功能一致的插件。如果你想要上架商店的插件功能与现有插件不完全重合，请在插件说明中补充其与现有插件的区别。
同时，如果你参考或基于他人发行的代码进行开发，请注意遵守各代码所使用的开源许可协议。 同时，如果你参考或基于他人发行的代码进行开发，请注意遵守各代码所使用的开源许可协议。
## Git 工作流
`master` 分支为 NoneBot 的开发分支，请在任何情况下都不要直接修改 `master` 分支，而是创建一个目标分支为 `nonebot:master` 的 Pull Request 来提交修改。
如果你不是 NoneBot 团队的成员，可在 fork 本仓库后，向本仓库的 `master` 分支发起 Pull Request，注意遵循先前提到的 commit message 规范创建 commit。我们将在 code review 通过后通过 squash merge 方式将您的贡献合并到主分支。