diff --git a/contribute/ci_rules.md b/contribute/ci_rules.md index 4d59ad3ae1785cbbfa294498da2cded385c0efbb..b08ede63896ba5f7be6a1e064bbb7e3e8ec3089e 100644 --- a/contribute/ci_rules.md +++ b/contribute/ci_rules.md @@ -1,16 +1,23 @@ # 文档开发流水线门禁 -## markdownlint +为提升文档质量,openEuler docs 仓引入了自动化动检视工具,对文档中低错问题进行排查。 -markdownlint 是一款检查 markdown 文件格式的工具。markdownlint规则介绍及本仓规则设置,请参考[检查规则](./markdownlint_rules.md)。可使用[工具](./markdownlint_tools.md)对markdownlint 进行批量修复。 +开发者提交PR后,会自动触发门禁进行检查。当返回如下结果时表示已经通过了工具检查: + +![](./figures/ci检查结果.jpg) + +通过门禁检查是PR合入的必要条件之一,检查项提示错误可在`Build Details`查查看错误详细信息。下面将对各个检查项进行介绍。 + +## Codespell Lint -> 说明: -> 开发者需要确保提交的文档已修复所有markdownlint错误,否则CI门禁报错,将无法合入。 +!! 这个有没有依据? -## 标签闭合 +## Error Label Check 链接、表格等内容元素建议使用markdown语法书写。如果需要使用HTML样式,请确保标签闭合。 +!!特殊情况要不要写下? + 错误示例 ```yaml @@ -39,9 +46,9 @@ markdownlint 是一款检查 markdown 文件格式的工具。markdownlint规则 ``` -> 说明:开发者需要确保提交的文档中HTML 标签已全部闭合,否则CI门禁报错,将无法合入。 +## Picture URL Check -## 引用链接 +!!这个是检查图片和手册链接一起的嘛?这个和link lint 有啥区别? 图片、网站、手册链接请检查路径地址是否正确。 @@ -74,10 +81,14 @@ markdownlint 是一款检查 markdown 文件格式的工具。markdownlint规则 [写作规范](./contribute/写作规范.md) ``` ->说明:开发者需要确保提交的文档中链接有效,否则CI门禁报错,将无法合入。 +## File Exist Check + +新增文档时,为了能在openEuler 文档官网展示,需要在对应`_menu.md`文件增加所在章节位置,否则此检查项报错。 -## 静态检查 +新增文档场景可参考快速入门的[指导](./contribution_process.md#新增文档),menu文件写作可参考[menu 文件写作规范](./menu_specifications.md)。 -新增文档时,为了能在openEuler 文档官网展示,需要在_menu.md文件增加对应文档位置。 +## Markdown Lint + +markdownlint 是一款检查 markdown 文件格式的工具。markdownlint规则介绍及本仓规则设置,请参考[检查规则](./markdownlint_rules.md)。可使用[工具](./markdownlint_tools.md)对markdownlint 进行批量修复。 ->说明:开发者需要确保提交新增文档同步提交了_menu.md文件修改,否则CI门禁报错,将无法合入。 +## Link Lint diff --git a/contribute/documentation_writing_specifications.md b/contribute/documentation_writing_specifications.md index 63c2911f58fcdcd22ef22d7039af73b8f46b1f2b..f4d9669013103184094c22770452ac779882d496 100644 --- a/contribute/documentation_writing_specifications.md +++ b/contribute/documentation_writing_specifications.md @@ -1,6 +1,10 @@ # 写作规范 -## 文档结构 +本写作规范针对openEuler docs 仓的文档结构、内容元素和语言风格提出规范要求,确保openEuler文档具备一致风格。 + +开发者开始openEuler文档写作前,建议先了解本规范内容,**欢迎提出改进意见**。 + +## 文档结构规范 特性手册内容一般包括概述、背景介绍、操作类文档(安装与部署、使用指南)、常见问题和附录,开发者可以根据项目实际情况增加或删减。 以[A-Tune 项目为例](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/A-Tune/A-Tune.html),可以参考如下内容: @@ -50,7 +54,7 @@ 附录可包含术语与缩略语介绍。 -## 内容元素 +## 内容元素规范 ### 命名 @@ -230,7 +234,7 @@ installation_and_deployment.md #新增‘安装与部署’文档 3. 第三项 ``` -- 嵌套列表:列表嵌套只需在子列表中的选项前面添加四个空格即可。 +- 嵌套列表:列表嵌套只需在子列表中的选项前面添加四个空格(注意不是Tab键)即可。 ```txt 1. 第一项: @@ -311,9 +315,9 @@ installation_and_deployment.md #新增‘安装与部署’文档 【规则】感叹号使用场景为可能引发严重后果的操作或设备安全、人身安全的警告。其他场景不允许使用感叹号。 -【规则】文内引用其他文档件事添加书名号,同时建议增加引用文档的跳转链接。例如:安装 openEuler 系统,安装方法参考《[openEuler 22.03 LTS SP2 安装指南](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/Installation/installation.html)》。 +【规则】文内引用其他文档时添加书名号,同时建议增加引用文档的跳转链接。例如:安装 openEuler 系统,安装方法参考《[openEuler 22.03 LTS SP2 安装指南](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/Installation/installation.html)》。 -## 语言风格 +## 语言风格规范 【规则】提交内容必须是与 openEuler 特性相关内容。 @@ -326,4 +330,4 @@ installation_and_deployment.md #新增‘安装与部署’文档 **文档贡献中不受欢迎的行为** 短时间内通过自动化工具,提交大量的PR,提交大量的处理诸如拼写错误,语法错误,日期错误,语句不通顺等“无害的错误”的修正。 -具体内容以及处理措施详见 [openEuler社区开发行为规范 V1.0](https://gitee.com/openeuler/community/blob/master/zh/technical-committee/governance/openEuler%E7%A4%BE%E5%8C%BA%E5%BC%80%E5%8F%91%E8%A1%8C%E4%B8%BA%E8%A7%84%E8%8C%83.md)。 +具体内容以及处理措施详见 [openEuler社区开发行为规范 V1.0](https://gitee.com/openeuler/community/blob/master/zh/technical-committee/governance/openEuler%E7%A4%BE%E5%8C%BA%E5%BC%80%E5%8F%91%E8%A1%8C%E4%B8%BA%E8%A7%84%E8%8C%83.md)。 \ No newline at end of file diff --git "a/contribute/figures/ci\346\243\200\346\237\245\347\273\223\346\236\234.jpg" "b/contribute/figures/ci\346\243\200\346\237\245\347\273\223\346\236\234.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..09ccd1e947319fc6fddf103ec9a1165bca4d4796 Binary files /dev/null and "b/contribute/figures/ci\346\243\200\346\237\245\347\273\223\346\236\234.jpg" differ