diff --git a/README.md b/README.md index 4caed2ef18bea9a5dd22dc3080d9246c3e05bfaa..f1d7637f004d4bdc46a05c4c719621d5e1ede5fd 100644 --- a/README.md +++ b/README.md @@ -221,112 +221,3 @@ RT-Thread Studio ：可以在 Studio 中下载源码包并创建 rt-thread 工 | [软件包开发指南](https://www.rt-thread.org/document/site/development-guide/package/package/) | [RT-Thread编程风格](https://github.com/RT-Thread/rt-thread/blob/master/documentation/coding_style_cn.md) | [向RT-Thread贡献代码](https://www.rt-thread.org/document/site/development-guide/github/github/) | | [STM32系列BSP制作教程](https://github.com/RT-Thread/rt-thread/blob/master/bsp/stm32/docs/STM32系列BSP制作教程.md) | [BSP开发规范](https://github.com/RT-Thread/rtthread-specification) | | | [传感器驱动开发指南](https://www.rt-thread.org/document/site/development-guide/sensor/sensor_driver_development/) | - -# RT-Thread 文档中心说明 - -[![License: Apache License 2.0](/_media/license-Apache2-0.svg)](https://github.com/RT-Thread/rt-thread/blob/master/LICENSE) -star -star -star -fork - -## 简介 - -为加强 RT-Thread 开源社区建设，加速完善 RT-Thread 中文文档中心内容，现将文档中心编辑权限予以开放，详情参见[在线文档开发介绍](#在线文档开发介绍)。欢迎社区小伙伴踊跃参与修改，提交PR。本文档中心使用 docsify 搭建。 - -## 目录说明 - -如下是 RT-Thread 在线文档中心的主要目录说明： - -development-tools：RT-Thread Studio IDE 和开发辅助工具 Env 的文档。 - -rt-thread-version：RT-Thread 各种版本，标准版本、nano版本、smart版本。 - -```tree -├─development-tools # RT-Thread 工具 -│ ├─env # Env 工具 -│ ├─kconfig # Kconfig 工具 -│ ├─rtthread-studio # RT-Thread Studio IDE -│ │ ├─applications # 应用笔记 -│ │ ├─changelog # 版本信息 -│ │ ├─drivers # 驱动开发 -│ │ ├─faq # 常见问题 -│ │ └─um # 用户手册 -│ └─scons # Scons 工具 -│ -├─rt-thread-version # RT-Thread 版本 -│ ├─rt-thread-nano # nano 版本 -│ ├─rt-thread-smart # smart 版本 -│ └─rt-thread-standard # 标准版本 -│ ├─application-note # 应用笔记 -│ ├─development-guide # 开发指南 -│ ├─programming-manual # 编程手册 -│ └─tutorial # 系列教程 -``` - -## 在线文档开发介绍 - -### 修改文档 - -当发现某文档一处错误时，在该文档页面最上方，点击 “修改此文档” - -![image-20210129101544289](other/figures/image-20210129101544289.png) - -跳转至该文档的 gitee 页面，点击 “编辑” - -> [!NOTE] -> 注：修改文档需要符合以下规则： -> ->（1）修改文档段落或添加文章后，文档中包含的中英文之间需要添加空格，可以使用 vscode-pangu 插件进行格式化。 -> ->（2）为文章添加图片时，不要使用 URL 方式进行链接（URL 可能会失效），需要将图片上传至该仓库，采用相对路径进行链接，保证图片有效性。[正确示范](https://gitee.com/rtthread/docs-online/pulls/47/files) vs [错误示范](https://gitee.com/rtthread/docs-online/pulls/44/files)。 -> ->（3）在编辑文档中的代码段时，需要符合 [RT-Thread 代码规范](https://github.com/RT-Thread/rt-thread/blob/master/documentation/coding_style_cn.md)。 -> - -![image-20210129101810207](other/figures/image-20210129101736085.png) - -进入可编辑状态，如将 12 改为 15 - -![image-20210129102019156](other/figures/image-20210129102019156.png) - -拉到最下面填写 提交信息，扩展信息可以根据情况填写，无误后，点击提交审核 - -![image-20210129104928115](other/figures/image-20210129102214629.png) - -> [!NOTE] -> 注：提交信息规范如下 -> -> 对某文档某段描述进行更新或完善，或删除某段描述：【更新文档】更新/增加/删除了 xxx -> -> 修改文档中的错误：【修改错误】修改 xxx 为 xxx - -然后等待审核即可，若审核不通过，还需要再次修改。 - -### 增加 / 删除文档 - -增加文档、删除文档则需要通过正常的 PR 流程进行提交（`fork -> clone -> 分支上开发 -> commit -> PR`）。 - -当需要增加文档时，最重要的是判断增加的是什么类型的文档，放在什么位置，以及文档名称等，然后进行提交，增加 / 删除 文档注意更新左侧栏。 - -- 如果不确定新增文档应该存放的位置，请新建 issue 咨询，或在论坛提问咨询，或在任意官方微信群咨询，确认后可以提交新文档。 -- 如果非常确定新文档的存放位置，可以直接新增并提交。 - -> [!NOTE] -> 注：提交信息规范如下 -> -> 增加一篇文档：【增加文档】xxxx 文档 -> -> 删除一篇文档：【删除文档】删除 xxx 文档，由于 xxx 原因删除 - -## 注意事项 - -- 文档命名使用英文，有必要的时候使用中杠。 -- 每篇文档使用一个 figures 文件夹。 -- 文档内容注意中英文之间增加一个空格。 -- 网站文档已开启缓存，测试没有效果时，请使用 CTRL+F5 强制刷新页面，或让浏览器进入无痕模式。 -- 标点符号需要使用中文标点符号；若出现连续、段落性英文，可以在句子间或该段落使用英文标点符号。 - -## 许可协议 - -![知识共享许可协议](_media/creativecommons.png)
本作品采用知识共享署名-非商业性使用 4.0 国际许可协议进行许可。 diff --git a/_sidebar.md b/_sidebar.md index 41128893fdfe59e5395296fb91e68150b7cb516a..8199e053180d1f91b4e19e7ce39c1f246b5cb1dd 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -2,3 +2,4 @@ - [新手指导](other/novice-guide/README.md) +- [PR提交规范](other/pr-rule/pr-rule.md) diff --git a/index.html b/index.html index 011f96a96084735b423bed5cee7e8c72b1b86d47..b92ec0f064530e86ac3ea2aeba5c1e3f78fc0c40 100644 --- a/index.html +++ b/index.html @@ -67,11 +67,12 @@ '/rt-thread-version/rt-thread-smart/.*/_sidebar.md': '/rt-thread-version/rt-thread-smart/_sidebar.md', '/rt-thread-version/rt-thread-standard/.*/_sidebar.md': '/rt-thread-version/rt-thread-standard/_sidebar.md', '/development-tools/.*/_sidebar.md': '/development-tools/_sidebar.md', + '/other/.*/_navbar.md': '/other/_sidebar.md', '/rt-thread-version/rt-thread-nano/.*/_navbar.md': '/rt-thread-version/rt-thread-nano/_navbar.md', '/rt-thread-version/rt-thread-smart/.*/_navbar.md': '/rt-thread-version/rt-thread-smart/_navbar.md', '/rt-thread-version/rt-thread-standard/.*/_navbar.md': '/rt-thread-version/rt-thread-standard/_navbar.md', '/development-tools/.*/_navbar.md': '/development-tools/_navbar.md', - '/other/.*/_navbar.md': '/other/novice-guide/_navbar.md', + '/other/.*/_navbar.md': '/other/_navbar.md', }, tabs: { persist: true, // default @@ -136,7 +137,7 @@ setInterval('transTip()', 1000); } var url = 'https://gitee.com/rtthread/docs-online/blob/master/' + vm.route.file - var editHtml = '[:pencil: 修改此文档 ](' + url + ')      [:page_with_curl:《修改规范说明》](/README?id=在线文档开发介绍)\n' + var editHtml = '[:pencil: 修改此文档 ](' + url + ')      [:page_with_curl:《PR提交规范》](/other/pr-rule/pr-rule)\n' return '\n\n'+ editHtml + diff --git a/other/novice-guide/_navbar.md b/other/_navbar.md similarity index 99% rename from other/novice-guide/_navbar.md rename to other/_navbar.md index cc051fadfe5417a6ef035807d33b9c34f64d250d..0cc217aab651011cd06dece91cc44b83f491691c 100644 --- a/other/novice-guide/_navbar.md +++ b/other/_navbar.md @@ -4,6 +4,7 @@ - [:uk: English](/) - [:cn: 中文](/) --> + * [新手指导](/other/novice-guide/README.md) * [标准版本](/rt-thread-version/rt-thread-standard/README.md) * [Nano 版本](/rt-thread-version/rt-thread-nano/an0038-nano-introduction.md) diff --git a/other/novice-guide/_sidebar.md b/other/_sidebar.md similarity index 61% rename from other/novice-guide/_sidebar.md rename to other/_sidebar.md index f97c32602c0ce88ae42940f51c662aa52a2e94f4..2eeae1f026dc0c6db70e825b132d3698f0d86479 100644 --- a/other/novice-guide/_sidebar.md +++ b/other/_sidebar.md @@ -1,3 +1,5 @@ + - [新手指导](/other/novice-guide/README.md) +- [PR提交规范](/other/pr-rule/pr-rule.md) diff --git a/other/novice-guide/README.md b/other/novice-guide/README.md index a4fc9f199c99694e6cfd4550bf6af2ef9a114616..6a86d52b0eb09ea23e1c8d646ec8139cb93cfadd 100644 --- a/other/novice-guide/README.md +++ b/other/novice-guide/README.md @@ -230,9 +230,8 @@ RT-Thread Studio ：可以在 Studio 中下载源码包并创建 rt-thread 工 star fork -## 简介 -为加强 RT-Thread 开源社区建设，加速完善 RT-Thread 中文文档中心内容，现将文档中心编辑权限予以开放，详情参见[在线文档开发介绍](#在线文档开发介绍)。欢迎社区小伙伴踊跃参与修改，提交PR。本文档中心使用 docsify 搭建。 +为加强 RT-Thread 开源社区建设，加速完善 RT-Thread 中文文档中心内容，现将文档中心编辑权限予以开放，详情参见 PR 提交规范。欢迎社区小伙伴踊跃参与修改，提交 PR。本文档中心使用 docsify 搭建。 ## 目录说明 @@ -240,93 +239,33 @@ RT-Thread Studio ：可以在 Studio 中下载源码包并创建 rt-thread 工 development-tools：RT-Thread Studio IDE 和开发辅助工具 Env 的文档。 -rt-thread-version：RT-Thread 各种版本，标准版本、nano版本、smart版本。 +rt-thread-version：RT-Thread 各种版本：标准版本、nano 版本、smart 版本。 ```tree -├─development-tools # RT-Thread 工具 -│ ├─env # Env 工具 -│ ├─kconfig # Kconfig 工具 -│ ├─rtthread-studio # RT-Thread Studio IDE -│ │ ├─applications # 应用笔记 -│ │ ├─changelog # 版本信息 -│ │ ├─drivers # 驱动开发 -│ │ ├─faq # 常见问题 -│ │ └─um # 用户手册 -│ └─scons # Scons 工具 -│ -├─rt-thread-version # RT-Thread 版本 -│ ├─rt-thread-nano # nano 版本 -│ ├─rt-thread-smart # smart 版本 -│ └─rt-thread-standard # 标准版本 -│ ├─application-note # 应用笔记 -│ ├─development-guide # 开发指南 -│ ├─programming-manual # 编程手册 -│ └─tutorial # 系列教程 + ├─development-tools # 工具 + │ ├─_sidebar.md # 侧边导航栏 + │ ├─build-config-system # 构建相关 + │ ├─env # Env 工具 + │ └─rtthread-studio # Studio IDE + ├─rt-thread-version # RT-Thread 各版本 + │ ├─rt-thread-nano # rt-thread nano 版本 + │ │ └─_sidebar.md # 侧边导航栏 + │ ├─rt-thread-smart # rt-thread smart 版本 + │ │ └─_sidebar.md # 侧边导航栏 + │ └─rt-thread-standard # rt-thread 标准版本 + │ ├─_sidebar.md # 侧边导航栏 + │ ├─application-note # 应用笔记 + │ ├─development-guide # 开发指南 + │ ├─packages-manual # 软件包指南 + │ ├─programming-manual # 编程手册 + │ └─tutorial # 小项目教程系列 + └─other + └─novice-guide # 新手入门 ``` -## 在线文档开发介绍 - -### 修改文档 - -当发现某文档一处错误时，在该文档页面最上方，点击 “修改此文档” - -![image-20210129101544289](../../other/figures/image-20210129101544289.png) - -跳转至该文档的 gitee 页面，点击 “编辑” - -> [!NOTE] -> 注：修改文档需要符合以下规则： -> ->（1）修改文档段落或添加文章后，文档中包含的中英文之间需要添加空格，可以使用 vscode-pangu 插件进行格式化。 -> ->（2）为文章添加图片时，不要使用 URL 方式进行链接（URL 可能会失效），需要将图片上传至该仓库，采用相对路径进行链接，保证图片有效性。[正确示范](https://gitee.com/rtthread/docs-online/pulls/47/files) vs [错误示范](https://gitee.com/rtthread/docs-online/pulls/44/files)。 -> ->（3）在编辑文档中的代码段时，需要符合 [RT-Thread 代码规范](https://github.com/RT-Thread/rt-thread/blob/master/documentation/coding_style_cn.md)。 -> - -![image-20210129101810207](../../other/figures/image-20210129101736085.png) - -进入可编辑状态，如将 12 改为 15 - -![image-20210129102019156](../../other/figures/image-20210129102019156.png) - -拉到最下面填写 提交信息，扩展信息可以根据情况填写，无误后，点击提交审核 - -![image-20210129104928115](../../other/figures/image-20210129102214629.png) - -> [!NOTE] -> 注：提交信息规范如下 -> -> 对某文档某段描述进行更新或完善，或删除某段描述：【更新文档】更新/增加/删除了 xxx -> -> 修改文档中的错误：【修改错误】修改 xxx 为 xxx - -然后等待审核即可，若审核不通过，还需要再次修改。 - -### 增加 / 删除文档 - -增加文档、删除文档则需要通过正常的 PR 流程进行提交（`fork -> clone -> 分支上开发 -> commit -> PR`）。 - -当需要增加文档时，最重要的是判断增加的是什么类型的文档，放在什么位置，以及文档名称等，然后进行提交，增加 / 删除 文档注意更新左侧栏。 - -- 如果不确定新增文档应该存放的位置，请新建 issue 咨询，或在论坛提问咨询，或在任意官方微信群咨询，确认后可以提交新文档。 -- 如果非常确定新文档的存放位置，可以直接新增并提交。 - -> [!NOTE] -> 注：提交信息规范如下 -> -> 增加一篇文档：【增加文档】xxxx 文档 -> -> 删除一篇文档：【删除文档】删除 xxx 文档，由于 xxx 原因删除 +## 许可协议 -## 注意事项 +![知识共享许可协议](../../_media/creativecommons.png)
本作品采用知识共享署名-非商业性使用 4.0 国际许可协议进行许可。 -- 文档命名使用英文，有必要时候使用中杠。 -- 每篇文档使用一个 figures 文件夹。 -- 文档内容注意中英文之间增加一个空格。 -- 网站文档已开启缓存，测试没有效果时，请使用 CTRL+F5 强制刷新页面，或让浏览器进入无痕模式。 -- 标点符号需要使用中文标点符号；若出现连续、段落性英文，可以在句子间或该段落使用英文标点符号。 -## 许可协议 -![知识共享许可协议](../../_media/creativecommons.png)
本作品采用知识共享署名-非商业性使用 4.0 国际许可协议进行许可。 \ No newline at end of file diff --git a/other/pr-rule/figures/file.png b/other/pr-rule/figures/file.png new file mode 100644 index 0000000000000000000000000000000000000000..e3cf6f5471b22b22dbccddf21a4edb6c888c4e59 Binary files /dev/null and b/other/pr-rule/figures/file.png differ diff --git a/other/figures/image-20210129101544289.png b/other/pr-rule/figures/image-20210129101544289.png similarity index 100% rename from other/figures/image-20210129101544289.png rename to other/pr-rule/figures/image-20210129101544289.png diff --git a/other/figures/image-20210129101736085.png b/other/pr-rule/figures/image-20210129101736085.png similarity index 100% rename from other/figures/image-20210129101736085.png rename to other/pr-rule/figures/image-20210129101736085.png diff --git a/other/figures/image-20210129102019156.png b/other/pr-rule/figures/image-20210129102019156.png similarity index 100% rename from other/figures/image-20210129102019156.png rename to other/pr-rule/figures/image-20210129102019156.png diff --git a/other/figures/image-20210129102214629.png b/other/pr-rule/figures/image-20210129102214629.png similarity index 100% rename from other/figures/image-20210129102214629.png rename to other/pr-rule/figures/image-20210129102214629.png diff --git a/other/pr-rule/figures/pangu.png b/other/pr-rule/figures/pangu.png new file mode 100644 index 0000000000000000000000000000000000000000..b41f5509354ad46d98b7bbca6f783c39dec8b575 Binary files /dev/null and b/other/pr-rule/figures/pangu.png differ diff --git a/other/pr-rule/figures/pr-sample.png b/other/pr-rule/figures/pr-sample.png new file mode 100644 index 0000000000000000000000000000000000000000..4ba62f626cb631f0674acbfc99fbc7a87475234d Binary files /dev/null and b/other/pr-rule/figures/pr-sample.png differ diff --git a/other/pr-rule/figures/rtt-bot.png b/other/pr-rule/figures/rtt-bot.png new file mode 100644 index 0000000000000000000000000000000000000000..baf6f2ad857c55cdbadd90f960d0e0faa3daa4e0 Binary files /dev/null and b/other/pr-rule/figures/rtt-bot.png differ diff --git a/other/pr-rule/pr-rule.md b/other/pr-rule/pr-rule.md new file mode 100644 index 0000000000000000000000000000000000000000..26ba7fb816df1d7daee32c9ac3a1dfcae254f0e3 --- /dev/null +++ b/other/pr-rule/pr-rule.md @@ -0,0 +1,117 @@ +# 文档中心 PR 提交规范 + +感谢您为 RT-Thread 官方文档中心做贡献！为了文档中心和开源社区的规范化发展，请您在提交 PR 之前请仔细阅读以下规则，并确保贡献的文档已遵守如下规则。 + +## PR 标题 + +PR 标题规范要求如下所示，请按照要求填写 PR 标题，否则 PR 将不予通过。 + +| 提交类型 | PR 标题规范要求 | +| -------------- | ----------------------------------------------- | +| 修改**已有**的文档 | 【修改】xxx 文档中 xxx 描述问题（或增加了 xxx 功能），文档支持在线修改 | +| 新增文档 | 【新增】xxx 文档 | +| 删除文档 | 【删除】xxx 文档，原因：xxxx | + +PR 标题示例： +1. 修改**已有**的文档：【修改】pin 设备驱动开发文档中引脚编号错误 +1. 修改**已有**的文档：【修改】为 spi 设备驱动开发文档增加了 xxx 描述 +1. 修改**已有**的文档：【修改】删除了 i2c 设备驱动开发文档中 xxx 段落 +1. 新增文档：【新增】pr 提交规则文档 +1. 删除文档：【删除】xxx 文档，由于 yyy，该文档不再使用 + +## 图片要求 + +| 推荐绘图工具 | 种类 | 特点 | 备注 | +| ------------ | -------- | ---------------------- | ------------------------------------------------------------ | +| Drawio | 多种类型 | 可在线绘图；可本地绘图 | [在线链接](https://www.draw.io/index.html) | +| Visio | 多种类型 | 本地绘图 | | +| WaveDrom | 时序 | 在线绘图；需要代码编写 | [在线链接](https://wavedrom.com/editor.html) | +| PlantUML | UML 类 | 在线绘图；需要代码编写 | [语法](https://plantuml.com/zh/sequence-diagram)；[在线链接](https://www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000) | + +- Drawio 绘图要求字体及大小为默认 Helvetica 12pt；线粗 1pt；并需提交矢量图，将 xxx.drawio 文件放入 figures 文件夹中提交。请确保矢量图与文档中截图命名相同。 +- Visio 绘图要求字体及大小为默认黑体 12pt；线粗 1pt；并需要提交矢量图，将 xxx.vsdx 文件放入 figures 文件夹中提交。请确保矢量图与文档中截图命名相同。 +- WaveDrom 与 PlantUML 绘图需提交图片的源码，将源码保存在 xxx.txt 中，放入 figures 文件夹中一起提交。请确保 txt 名与文档中截图命名相同。 +- 对截图的要求：截图的四周留白尽量减少。 + +>[!NOTE] +> 注意：为文章添加图片时，不要使用 URL 方式进行链接（URL 可能会失效），需要将图片上传至该仓库，采用相对路径进行链接，保证图片有效性。[正确示范](https://gitee.com/rtthread/docs-online/pulls/47/files) vs [错误示范](https://gitee.com/rtthread/docs-online/pulls/44/files)。 + +## 修改文档 + +文档支持在线修改，当发现某文档一处错误时，在该文档页面最上方，点击 “修改此文档” + +![image-20210129101544289](figures/image-20210129101544289.png) + +跳转至该文档的 gitee 页面，点击 “编辑” + +![image-20210129101810207](figures/image-20210129101736085.png) + +进入可编辑状态，如将 12 改为 15 + +![image-20210129102019156](figures/image-20210129102019156.png) + +拉到最下面填写 提交信息，扩展信息可以根据情况填写，无误后，点击提交审核 + +![image-20210129104928115](figures/pr-sample.png) + + +> [!NOTE] +> 修改文档需要符合以下规则： +> +>（1）修改文档段落或添加文章后，文档中包含的中英文之间需要添加空格，可以使用 vscode-pangu 插件进行格式化。注意 pangu 格式化会**破坏加粗格式**，格式化完成请再次检查加粗格式并修改。 +> +>（2）在编辑文档中的代码段时，需要符合 [RT-Thread 代码规范](https://github.com/RT-Thread/rt-thread/blob/master/documentation/coding_style_cn.md)；若进行代码修改，请描述清楚修改原因。 +> +>（3）中文正文中标点符号需要使用中文标点符号；若出现连续、段落性英文，需在句子间或该段落使用英文标点符号。 +> + +## 删除文档 + +删除文档则需要通过正常的 PR 流程进行提交（`fork -> clone -> 分支上开发 -> commit -> PR`），谨慎删除文档并描述删除原因。 + +## 新增文档 + +1. 新文档归属：首先需要确认新增的文档隶属于哪个模块下。 + + ``` + ├─development-tools # 工具 + │ ├─_sidebar.md # 侧边导航栏 + │ ├─build-config-system # 构建相关 + │ ├─env # Env 工具 + │ └─rtthread-studio # Studio IDE + ├─rt-thread-version # RT-Thread 各版本 + │ ├─rt-thread-nano # rt-thread nano 版本 + │ │ └─_sidebar.md # 侧边导航栏 + │ ├─rt-thread-smart # rt-thread smart 版本 + │ │ └─_sidebar.md # 侧边导航栏 + │ └─rt-thread-standard # rt-thread 标准版本 + │ ├─_sidebar.md # 侧边导航栏 + │ ├─application-note # 应用笔记 + │ ├─development-guide # 开发指南 + │ ├─packages-manual # 软件包指南 + │ ├─programming-manual # 编程手册 + │ └─tutorial # 小项目教程系列 + └─other + ├─novice-guide # 新手入门 + └─pr-rule # PR 提交规范 + ``` + +> [!NOTE] +> 注意：如果不确定新增文档应该存放的位置，请新建 issue 咨询，确认新增位置后可以提交新文档。 + +2. 新文档命名：文档及文件夹命名使用英文，有必要时候使用中杠链接单词，如 device-ipc。 +3. 新文档结构：每篇文档使用一个 figures 文件夹，存储本篇文档中使用的图片及图片源码。 + +![image-20220826142136846](figures/file.png) + +4. 更新文档中心导航栏：需要将新增的文档放在相应位置的导航栏中，修改的文件为对应的 `_sidebar.md` 文件。 + +## 提交后自查 + +在 PR 提交完成之后，文档中心会触发 rtthread-bot 机器人执行 pipeline CI 测试，将测试结果返回在 test 表格中，如下图所示。请点击 View 预览修改处，若有问题则及时修改；若无问题请等待审核合并。 + +![image-20220826093636367](figures/rtt-bot.png) + +> [!NOTE] +> 注意：网站文档已开启缓存，测试没有效果时，请使用 CTRL+F5 强制刷新页面，或让浏览器进入无痕模式。 +