diff --git "a/contribute/MarkDown\345\270\270\347\224\250\350\257\255\346\263\225\345\217\202\350\200\203.md" "b/contribute/MarkDown\345\270\270\347\224\250\350\257\255\346\263\225\345\217\202\350\200\203.md" deleted file mode 100644 index f2f4a6098dd5d950f931b75317a1262eb3b9ae12..0000000000000000000000000000000000000000 --- "a/contribute/MarkDown\345\270\270\347\224\250\350\257\255\346\263\225\345\217\202\350\200\203.md" +++ /dev/null @@ -1,140 +0,0 @@ -# MarkDown常用语法参考 - -## 标题 - -使用\#号标记:使用 \# 号可表示 1-6 级标题,一级标题对应一个 \# 号,二级标题对应两个 \# 号,以此类推。 - -``` -# 一级标题 -## 二级标题 -### 三级标题 -#### 四级标题 -##### 五级标题 -###### 六级标题 -``` - -## 字体 - -- 斜体:使用一个星号(\*)表示斜体。 - - ``` - *斜体文本* - ``` - -- 粗体:使用两个星号(\*\*)表示粗体。 - - ``` - **粗体文本** - ``` - -- 粗斜体:使用3个星号(\*\*\*)表示粗斜体。 - - ``` - ***粗斜体文本*** - ``` - - -## 列表 - -- 无序列表:无序列表使用星号(**\***)、加号(**+**)或是减号(**-**)作为列表标记,这些标记后面要添加一个空格,然后再填写内容。同一个无序列表,建议使用同一个符号。 - - ``` - * 第一项 - * 第二项 - * 第三项 - - + 第一项 - + 第二项 - + 第三项 - - - - 第一项 - - 第二项 - - 第三项 - ``` - - -- 有序列表:有序列表使用数字并加上 **.** 号来表示。 - - ``` - 1. 第一项 - 2. 第二项 - 3. 第三项 - ``` - - -- 嵌套列表:列表嵌套只需在子列表中的选项前面添加四个空格即可。 - - ``` - 1. 第一项: - - 第一项嵌套的第一个元素 - - 第一项嵌套的第二个元素 - 2. 第二项: - - 第二项嵌套的第一个元素 - - 第二项嵌套的第二个元素 - ``` - - -## 引用 - -Markdown 区块引用是在段落开头使用 **\>** 符号 ,然后后面紧跟一个**空格**符号。 - -``` -> 说明: -``` - -## 代码 - -- 行间代码:如果是段落上的一个函数或片段的代码可以用反引号把它包起来(**\`**)。 - -``` -`printf()` 函数 -``` - -- 代码块:可以用 **\`\`\`** 包裹一段代码。 - -``` -``` -select * from table; -``` -``` - -## 链接 - -链接使用方法如下: - -``` -[链接名称](链接地址) -``` - -## 图片 - -图片使用方法如下: - -``` -![alt 属性文本](图片地址) - -![alt 属性文本](图片地址 "可选标题") -``` - -- 开头一个感叹号 (!)。 -- 接着一个方括号,里面放上图片的替代文字。 -- 接着一个普通括号,里面放上图片的网址,最后还可以用引号包住并加上选择性的 'title' 属性的文字。 - -## 表格 - -Markdown 制作表格使用 **|** 来分隔不同的单元格,使用 **-** 来分隔表头和其他行。语法格式如下: - -``` -| 表头 | 表头 | -| ---- | ---- | -| 单元格 | 单元格 | -| 单元格 | 单元格 | -``` - -我们可以设置表格的对齐方式: - -- -: 设置内容和标题栏居右对齐。 -- :- 设置内容和标题栏居左对齐。 -- :-: 设置内容和标题栏居中对齐。 - diff --git a/contribute/_menu.md b/contribute/_menu.md index 82d53c7bfa0dc479a4247decba91114f2f7f61ef..456b5577ca9091ae584b352f641acdf98e9820e3 100644 --- a/contribute/_menu.md +++ b/contribute/_menu.md @@ -13,13 +13,7 @@ children: - label: '英文文档贡献指导' href: './english_doc_contribute.md' - label: '文档写作规范' - children: - - label: '文档写作规范' - href: './documentation_writing_specifications.md' - - label: 'MarkDown常用语法参考' - href: './MarkDown常用语法参考.md' - - label: 'markdownlint检查规则' - href: './markdownlint检查规则.md' - - label: 'markdownlint错误修复工具' - href: './markdownlint错误修复工具.md' + reference: './documentation_writing_specifications.md' + - label: '文档发布流水线门禁' + reference: './ci_rules.md' --- \ No newline at end of file diff --git a/contribute/ci_rules.md b/contribute/ci_rules.md new file mode 100644 index 0000000000000000000000000000000000000000..4d59ad3ae1785cbbfa294498da2cded385c0efbb --- /dev/null +++ b/contribute/ci_rules.md @@ -0,0 +1,83 @@ +# 文档开发流水线门禁 + +## markdownlint + +markdownlint 是一款检查 markdown 文件格式的工具。markdownlint规则介绍及本仓规则设置,请参考[检查规则](./markdownlint_rules.md)。可使用[工具](./markdownlint_tools.md)对markdownlint 进行批量修复。 + +> 说明: +> 开发者需要确保提交的文档已修复所有markdownlint错误,否则CI门禁报错,将无法合入。 + +## 标签闭合 + +链接、表格等内容元素建议使用markdown语法书写。如果需要使用HTML样式,请确保标签闭合。 + +错误示例 + + ```yaml + + + + + +
Header 1 + Header 2
Data 1 + Data 2
+ ``` + +正确示例 + + ```yaml + + + + + + + + + +
Header 1Header 2
Data 1Data 2
+ ``` + +> 说明:开发者需要确保提交的文档中HTML 标签已全部闭合,否则CI门禁报错,将无法合入。 + +## 引用链接 + +图片、网站、手册链接请检查路径地址是否正确。 + +反例 + +- 失效的网站链接 + + ```text + [错误官网](https://doc.openeuler.org/zh/) + ``` + +- 错误的相对路径 + + ```text + [写作规范](../写作规范.md) + ``` + +​ +正例 + +- 网站链接 + + ```text + [错误官网](https://docs.openeuler.org/zh/) + ``` + +- 相对路径 + + ```text + [写作规范](./contribute/写作规范.md) + ``` + +>说明:开发者需要确保提交的文档中链接有效,否则CI门禁报错,将无法合入。 + +## 静态检查 + +新增文档时,为了能在openEuler 文档官网展示,需要在_menu.md文件增加对应文档位置。 + +>说明:开发者需要确保提交新增文档同步提交了_menu.md文件修改,否则CI门禁报错,将无法合入。 diff --git a/contribute/documentation_writing_specifications.md b/contribute/documentation_writing_specifications.md index 1107ada6046e342f7126abe4ce77dc7d4a53c12f..63c2911f58fcdcd22ef22d7039af73b8f46b1f2b 100644 --- a/contribute/documentation_writing_specifications.md +++ b/contribute/documentation_writing_specifications.md @@ -1,89 +1,329 @@ -# 文档写作规范 +# 写作规范 -## 写作规范 +## 文档结构 -文档结构、内容元素、语言风格书写请参考[写作规范](./写作规范.md)。 +特性手册内容一般包括概述、背景介绍、操作类文档(安装与部署、使用指南)、常见问题和附录,开发者可以根据项目实际情况增加或删减。 +以[A-Tune 项目为例](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/A-Tune/A-Tune.html),可以参考如下内容: -## 流水线门禁 +### 概述 -### Markdownlint +一句话介绍特性定义与功能。 -markdownlint 是一款检查 Markdown 文件格式的工具。markdownlint规则介绍及本仓规则设置,请参考[检查规则](./markdownlint检查规则.md)。可使用[工具](./markdownlint错误修复工具.md)对markdownlint 进行批量修复。 +【举例】 -> 说明: -> 开发者需要确保提交的文档已修复所有markdownlint错误,否则CI门禁报错,将无法合入。 +```markdown +本文档介绍openEuler系统性能自优化软件A-Tune的安装部署和使用方法,以指导开发者快速了解并使用A-Tune。 +``` -### 标签闭合 +### 背景介绍 -链接、表格等内容元素建议使用markdown语法书写。如果需要使用HTML样式,请确保标签闭合。 +背景介绍类文档写明特性背景与简介、架构说明等。常见文档标题:`认识xxx`。 -错误示例 +### 操作类文档 - ```yaml - - - - - -
Header 1 - Header 2
Data 1 - Data 2
- ``` +操作类文档写明步骤、注意事项、前提条件等,以便能对其他开发者起到帮助。 -正确示例 - - ```yaml - - - - - - - - - -
Header 1Header 2
Data 1Data 2
- ``` +- 使用说明 -> 说明:开发者需要确保提交的文档中HTML 标签已全部闭合,否则CI门禁报错,将无法合入。 +说明此操作在什么场景下使用可以解决开发者的什么问题。 -### 引用链接 +- 环境要求 -图片、网站、手册链接请检查路径地址是否正确。 +执行此操作需要准备的软硬件环境、权限以及其它约束条件。 -反例 +- 操作步骤 -- 失效的网站链接 +具体的操作步骤,需要注意如下事项: + - 建议一步一个操作步骤,不建议多个操作步骤合并在一个步骤中描写。 + - 如果操作可选,要明确可选条件。 + - 开发步骤中,涉及调用接口(例如使用了工具或者 SQL 语句),需要对使用的接口进行说明。 - ```text - [错误官网](https://doc.openeuler.org/zh/) - ``` +- 结果验证 + +说明如何验证操作结果正确。如果验证操作与步骤强相关,可以在步骤中描述。例如,执行 SQL 语句的返回信息。 + +### 常见问题 + +此类文档应该包括问题描述、产生原因及解决办法。 + +### 附录 + +附录可包含术语与缩略语介绍。 + +## 内容元素 + +### 命名 + +对于新增文档,请在对应的文件目录下新增 MarkDown 文档(即以 .md 结尾的文件)。 + +【规则】新增文档名称不能与已有文档重名,如果有请重新命名。 + +【规则】文档需要以**英文**命名。 + +【规则】文件名中不能包含括号,会导致文件目录无法正常显示。可以将括号修改为可识别的下划线(\_)或者中划线(-)。 + +【举例】 + +```text +installation_and_deployment.md #新增‘安装与部署’文档 +``` + +### 标题 + +【规则】标题尽量采用简洁的语句概况反映章节的中心内容,注意不要省略必要的信息。 + +【规则】操作类文档标题尽量用动宾结构(例如:申请权限);相同级别,相同类型的标题结构保持一致。 + +【规则】标题不使用标点符号结尾,标题中尽量采用圆括号来表示补充说明,标题中不能出现特殊字符,如“?”。 + +【规则】标题与正文使用 1 整行换行隔开。 + +【规则】标题使用 “#” 空格连接标题名,标题级别一次只能增加一个级别且第一个标题应该是顶层标题。 + +【举例】 + +```markdown +# 一级标题 +## 二级标题 +### 三级标题 +#### 四级标题 +##### 五级标题 +###### 六级标题 +``` + +### 正文 + +【使用方法】 + +- 斜体:使用一个星号(\*)表示斜体。 + + ```txt + *斜体文本* + ``` + +- 粗体:使用两个星号(\*\*)表示粗体。 + + ```txt + **粗体文本** + ``` + +- 粗斜体:使用3个星号(\*\*\*)表示粗斜体。 + + ```txt + ***粗斜体文本*** + ``` + +- 转义:对特定内容使用转义符 \。 + + ```txt + \<转义的标记符号> + ``` + +【规则】该转义的字符必须严格用转义符 \ 。 + +【规则】如果有连续两个转义符,转义符之间要有空格 \{ \}。 + +【规则】国际化:需同时提供中英文文档,可联系协助翻译;如需参与英文文档贡献,可参考[指南](./english_doc_contribute.md)。 + +### 空格 + +【规则】编辑文档时中文和英文之间**建议**加空格,页面展示更美观,请保持全文一致。如果是产品名词如 “豆瓣FM”,请按照官方定义格式书写。 + + 例如:openEuler 是一款开源操作系统。当前 openEuler 内核源于 Linux ,支持鲲鹏及其它多种处理器。 + +【规则】中文和数字之间加空格。 + +【规则】数字和单位之间不加空格。 + +【规则】全角标点与其他字符之间不加空格。 + + 例如:刚刚成为了 openEuler 的 maintainer,好开心。 + +### 图片 + +【使用方法】 + +```bash +![alt 属性文本](图片地址) + +![alt 属性文本](图片地址 "可选标题") +``` + +【规则】图片统一存放到文档同级目录下的 figures 文件夹中。例如,[A-Tune用户指南](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/A-Tune/A-Tune.html)中的手册中使用的图片,统一存储在 [A-Tune](https://gitee.com/openeuler/docs/tree/stable2-22.03_LTS_SP2/docs/zh/docs/A-Tune/figures) 路径下。该文件夹下的文件引用图片时,使用相对引用。 + +【规则】请使用原创图片,避免存在知识产权侵权风险。 + +【规则】图文配合使用,切忌图文分离。 + +【规则】图片格式首选 png,此外也接受 jpg。图片的高不超过 640px,宽不超过 393px,图片大小建议不超过 150K。 + +【规则】中文用中文插图,英文用英文插图。 + +【规则】图片路径不能包含中文。 -- 错误的相对路径 +【规则】如果是截图,请在允许的范围内只保留有用的信息。图形中需要突出的关键信息,可增加红色框线或者文字备注说明。 - ```text - [写作规范](../写作规范.md) +【举例】 +​图片以 `![](./figures/pic_name.png)` 格式书写,“./” 不可少,否则图片无法显示到现网。 + +### 代码块 + +代码示例说明了如何实现特定功能,开发人员使用代码示例来编写和调试代码。 + +【规则】代码的逻辑和语法正确。 + +【规则】代码的输入和输出尽可能的分开。 + +【规则】保证代码中关键步骤要有注释说明。 + +【规则】文中行内代码和命令行使用 1 对反引号,如: `代码行`。 + +【规则】块级代码使用 3 个顿号或 4 个空格(不能用 TAB 键)缩进,且上下均用整行隔开。 + +【举例】 + +- 行内代码 + + ```txt + `printf()` 函数 ``` -​ -正例 +- 块级代码 -- 网站链接 + ```python + #!/usr/bin/env python3 + print("Hello, World!"); + ``` - ```text - [错误官网](https://docs.openeuler.org/zh/) + ```c + #include + int main(void) + { + printf("Hello world\n"); + } ``` +### 列表 + +- 无序列表:无序列表使用星号(**\***)、加号(**+**)或是减号(**-**)作为列表标记,这些标记后面要添加一个空格,然后再填写内容。同一个无序列表,建议使用同一个符号。 + + ```txt + * 第一项 + * 第二项 + * 第三项 + + + 第一项 + + 第二项 + + 第三项 + + + - 第一项 + - 第二项 + - 第三项 + ``` + +- 有序列表:有序列表使用数字并加上 **.** 号来表示。 + + ```txt + 1. 第一项 + 2. 第二项 + 3. 第三项 + ``` + +- 嵌套列表:列表嵌套只需在子列表中的选项前面添加四个空格即可。 + + ```txt + 1. 第一项: + - 第一项嵌套的第一个元素 + - 第一项嵌套的第二个元素 + 2. 第二项: + - 第二项嵌套的第一个元素 + - 第二项嵌套的第二个元素 + ``` + +【规则】有明显先后逻辑顺序情况请使用有序列表,并列关系、多选一情况请使用无序列表。 + +【规则】当项目列表是术语、短语时,统一不加标点符号。 + +【规则】当项目列表是句子时,统一加句号。 + +【规则】特殊情况下如果不能避免出现短语和句子混合的情况,统一加句号。 + +【规则】项目列表前几项以分号结尾,最后一项以句号结尾的形式也可以接受。 + +### 注释符号 + +文档中会出现以下注释符号,代表不同的使用场景和提示程度。如果需要提示用户注意的信息,可以根据重要程度选择对应的注释符号。 + +| 标识符 | 用途/含义 | 使用方法 | +|--------|------------------------------------------------------------------|-----------------------------------------------------------------------------| +| 警告 | 如未按该警告内容操作,可能会导致结果异常,且不可恢复。 | `>![](./public_sys-resources/icon-warning.gif)**警告:**`
`>正文内容` | +| 注意 | 如未按该注意事项操作,可能会导致任务中断或结果异常,但是可恢复。 | `>![](./public_sys-resources/icon-notice.gif)**注意:**`
`>正文内容` | +| 说明 | 提供帮助提示或有用的参考信息 | `>![](./public_sys-resources/icon-note.gif)**说明:**`
`>正文内容` | + +### 链接 + +【规则】链接需要确保指向的目标文件存在,否则会造成链接跳转不正常,不建议使用 HTML 的链接样式。 + +【举例】 + +```markdown +- 网站链接 +这是一个链接 [菜鸟教程](https://www.runoob.com)。 + - 相对路径 + [文档开发流水线门禁](./ci_rules.md) +``` - ```text - [写作规范](./contribute/写作规范.md) - ``` +### 表格 + +【规则】markdown 文档中请使用以下方式创建表格,不建议使用 HTML 的表格样式。 + +【举例】 + +| 表头1 | 表头2 | +| ---------- | -------- | +| 单元格1 | 单元格2 | +| 单元格4 | 单元格4 | + +【使用方法】 +设置表格的对齐方式: + +- -: 设置内容和标题栏居右对齐。 +- :- 设置内容和标题栏居左对齐。 +- :-: 设置内容和标题栏居中对齐。 + +【规则】当表格内一列全部是术语、短语时,统一不加标点符号。 + +【规则】当表格内一列全部是句子时,统一加句号。 + +【规则】特殊情况下如果不能避免出现短语和句子混合的情况,统一加句号。 + +### 标点符号 + +【规则】单位与数字之间不建议加空格,比如 50m,10kg,64Kbit/s。 + +【规则】对于有序/无序列表,如果是长句子,建议统一以句号结尾,如果是短语,结尾可不用标点。**重点是前后一致,要么都加,要么都不加**。 + +【规则】中文文档使用全角标点。 + +【规则】数字使用半角字符。 + +【规则】感叹号使用场景为可能引发严重后果的操作或设备安全、人身安全的警告。其他场景不允许使用感叹号。 + +【规则】文内引用其他文档件事添加书名号,同时建议增加引用文档的跳转链接。例如:安装 openEuler 系统,安装方法参考《[openEuler 22.03 LTS SP2 安装指南](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/Installation/installation.html)》。 + +## 语言风格 + +【规则】提交内容必须是与 openEuler 特性相关内容。 + +【规则】内容不能包含敏感信息、有强烈的种族歧视或性别歧视的内容。 ->说明:开发者需要确保提交的文档中链接有效,否则CI门禁报错,将无法合入。 +【规则】提交的内容必须是原创内容,不得侵犯他人知识产权。 -### 静态检查 +【规则】提交的内容必须客观、真实,不允许使用夸大宣传等词汇。 -新增文档时,为了能在openEuler 文档官网展示,需要在_menu.md文件增加对应文档位置。 +**文档贡献中不受欢迎的行为** ->说明:开发者需要确保提交新增文档同步提交了_menu.md文件修改,否则CI门禁报错,将无法合入。 +短时间内通过自动化工具,提交大量的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)。 diff --git "a/contribute/markdownlint\346\243\200\346\237\245\350\247\204\345\210\231.md" b/contribute/markdownlint_rules.md similarity index 99% rename from "contribute/markdownlint\346\243\200\346\237\245\350\247\204\345\210\231.md" rename to contribute/markdownlint_rules.md index d7a8cf07dd5bc3278b5176fe7e97ed8d398dbe41..2dc12ff942b9938a545b8e8ae8693b914bfe82ea 100644 --- "a/contribute/markdownlint\346\243\200\346\237\245\350\247\204\345\210\231.md" +++ b/contribute/markdownlint_rules.md @@ -820,7 +820,7 @@ markdownlint 是一款检查 Markdown 文件格式的工具,可以根据设置 [EOF] ```` -## OpenEuler 规则设置 +## openEuler 规则设置 - openEuler 规则采用如下方案: diff --git "a/contribute/markdownlint\351\224\231\350\257\257\344\277\256\345\244\215\345\267\245\345\205\267.md" b/contribute/markdownlint_tools.md similarity index 100% rename from "contribute/markdownlint\351\224\231\350\257\257\344\277\256\345\244\215\345\267\245\345\205\267.md" rename to contribute/markdownlint_tools.md diff --git a/contribute/public_sys-resources/icon-caution.gif b/contribute/public_sys-resources/icon-caution.gif new file mode 100644 index 0000000000000000000000000000000000000000..6e90d7cfc2193e39e10bb58c38d01a23f045d571 Binary files /dev/null and b/contribute/public_sys-resources/icon-caution.gif differ diff --git a/contribute/public_sys-resources/icon-danger.gif b/contribute/public_sys-resources/icon-danger.gif new file mode 100644 index 0000000000000000000000000000000000000000..6e90d7cfc2193e39e10bb58c38d01a23f045d571 Binary files /dev/null and b/contribute/public_sys-resources/icon-danger.gif differ diff --git a/contribute/public_sys-resources/icon-note.gif b/contribute/public_sys-resources/icon-note.gif new file mode 100644 index 0000000000000000000000000000000000000000..6314297e45c1de184204098efd4814d6dc8b1cda Binary files /dev/null and b/contribute/public_sys-resources/icon-note.gif differ diff --git a/contribute/public_sys-resources/icon-notice.gif b/contribute/public_sys-resources/icon-notice.gif new file mode 100644 index 0000000000000000000000000000000000000000..86024f61b691400bea99e5b1f506d9d9aef36e27 Binary files /dev/null and b/contribute/public_sys-resources/icon-notice.gif differ diff --git a/contribute/public_sys-resources/icon-tip.gif b/contribute/public_sys-resources/icon-tip.gif new file mode 100644 index 0000000000000000000000000000000000000000..93aa72053b510e456b149f36a0972703ea9999b7 Binary files /dev/null and b/contribute/public_sys-resources/icon-tip.gif differ diff --git a/contribute/public_sys-resources/icon-warning.gif b/contribute/public_sys-resources/icon-warning.gif new file mode 100644 index 0000000000000000000000000000000000000000..6e90d7cfc2193e39e10bb58c38d01a23f045d571 Binary files /dev/null and b/contribute/public_sys-resources/icon-warning.gif differ diff --git "a/contribute/\345\206\231\344\275\234\350\247\204\350\214\203.md" "b/contribute/\345\206\231\344\275\234\350\247\204\350\214\203.md" deleted file mode 100644 index 4c9566d4ca823048228c8cb544225e62a87d2632..0000000000000000000000000000000000000000 --- "a/contribute/\345\206\231\344\275\234\350\247\204\350\214\203.md" +++ /dev/null @@ -1,302 +0,0 @@ -# 写作规范 - -## 文档内容 - -根据文档分类如用户指南、开发者指南等,选择合适的大纲,要求能简洁清晰的实现文档的目的。 - -- 开源项目做什么 -- 什么语言编写 -- 项目维护、CI、依赖更新状态 -- 项目可用版本及其他版本 -- Demo 或官网地址 -- 功能特点 -- 获取 -- 安装 -- 使用(操作步骤、接口文档、开发指南等) -- FAQ - -拟定文档大纲,编辑文档内容,针对文档内容做如下规范。 - -- 提交内容必须是与 openEuler 特性相关内容。 -- 内容不能包含敏感信息、有强烈的种族歧视或性别歧视的内容。 -- 提交的内容必须是原创内容,不得侵犯他人知识产权。 -- 提交的内容必须客观、真实,不允许使用夸大宣传等词汇。 - -## 文档结构 - -项目手册内容一般包括用户指南、背景介绍、操作类文档(安装与部署、使用指南)、常见问题和附录,写作者可以根据项目实际情况增加或删减。 -以[A-Tune 项目为例](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/A-Tune/A-Tune.html),可以参考如下内容: - -- **用户指南** - - 用户指南包含项目介绍和读者对象。 - -- **背景介绍类** - - 背景介绍类文档写明项目背景与简介、架构说明等。 - -- **操作类文档** - - 操作类文档写明步骤、注意事项、前提条件等,以便能对其他开发者起到帮助。 - - - 使用说明 - - 说明此操作在什么场景下使用可以解决用户的什么问题。 - - - 环境要求 - - 执行此操作需要用户准备的软硬件环境、权限以及其它约束条件。 - - - 操作步骤 - - 具体的操作步骤,需要注意如下事项: - - - 建议一步一个操作步骤,不建议多个操作步骤合并在一个步骤中描写。 - - 如果操作可选,要明确可选条件。 - - 开发步骤中,涉及调用接口(例如使用了工具或者 SQL 语句),需要对使用的接口进行说明。 - - - 结果验证 - - 说明如何验证操作结果正确。如果验证操作与步骤强相关,可以在步骤中描述。例如,执行 SQL 语句的返回信息。 - -- **常见问题** - 此类文档应该包括问题描述、产生原因及解决办法。 - -- **附录** - 附录可包含术语与缩略语介绍。 - -## 命名 - -对于新增文档,请在对应的文件目录下新增 MarkDown 文档(即以 .md 结尾的文件)。文档命名需要根据文档的内容声明。 - -- 新增文档名称不能与已有文档重名,如果有请重新命名。 -- 新增文档之后,需要在 menu 文件夹下的 index 文件中新增对应的目录,否则新增文件无法显示。目录层级不建议超过三级。 -- 文件名中不能包含括号,会导致文件目录无法正常显示。可以将括号修改为可识别的下划线(\_)或者中划线(-)。 - -## 标题 - -- 标题尽量采用简洁的语句概况反映章节的中心内容,注意不要省略必要的信息。例如:xxx概述,如果用概述来代替,就会导致读者无法从标题中获取到有用信息。 -- 操作类文档标题尽量用动宾结构(例如:申请权限)。 -- 相同级别,相同类型的标题结构保持一致。 -- 标题不使用标点符号结尾。 -- 标题中尽量采用圆括号来表示补充说明,标题中不能出现特殊字符,如“?”。 -- 标题与正文使用 1 整行换行隔开。 -- 标题使用 “#” 空格连接标题名,标题级别一次只能增加一个级别且第一个标题应该是顶层标题。 - -## 目录 - -文档为以 .md 结尾的文件,存储在 路径下。 - -docs 文件夹中包含以下内容: - -- zh:全量版中文资料。 -- en:全量版英文资料。 - -根据文档所属的手册,选择对应的文件夹。 - -- 目录层级不建议过深。 -- doc 仓库内新增文档需要同步修改 menu.json 文件,才可以在官网文档页面展示该文档。 -- doc 官网会在右侧自动生成文档的章节目录,不建议额外增加 TOC 目录。 - -## 正文 - -- 可使用*斜体* **加粗**样式。 -- 该转义的字符必须严格用转义符 \ ,例如 \* \< \> \_等。 -- 如果有连续两个转义符,转义符之间要有空格 \{ \}。 -- 国际化:需同时提供中英文文档,可联系协助翻译。 - -## 空格 - -- 编辑文档时中文和英文之间建议加空格,页面展示更美观,请保持全文一致。如果是产品名词如 “豆瓣FM”,请按照官方定义格式书写。 - - 例如:openEuler 是一款开源操作系统。当前 openEuler 内核源于 Linux ,支持鲲鹏及其它多种处理器。 - -- 中文和数字之间加空格。 - -- 数字和单位之间不加空格。 - -- 链接与正文之间加空格。 - -- 全角标点与其他字符之间不加空格。 - - 例如:刚刚成为了 openEuler 的 maintainer,好开心。 - -## 图片 - -- 图片统一存放到文档同级目录下的 figures 文件夹中。例如,[A-Tune用户指南](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/A-Tune/A-Tune.html)中的手册中使用的图片,统一存储在 [A-Tune](https://gitee.com/openeuler/docs/tree/stable2-22.03_LTS_SP2/docs/zh/docs/A-Tune/figures) 路径下。该文件夹下的文件引用图片时,使用相对引用。 -- 请使用原创图片,避免存在知识产权侵权风险。 -- 图形清晰可辨识,图形信息完整,例如流程图有“开始”和“结束”。 -- 图形逻辑清晰。 -- 图文配合使用,切忌图文分离。 -- 图片格式首选 png,此外也接受 jpg。图片的高不超过 640px,宽不超过 393px,图片大小建议不超过 150K。 -- 中文用中文插图,英文用英文插图。 -- 图片路径不能包含中文。 -- 图片后缀也必须是小写,不能出现 .PNG 这种大写后缀 -- 图片建议根据内容命名,只用数字序列不利于后续图片的继承。 -- 如果是截图,请在允许的范围内只保留有用的信息。图形中需要突出的关键信息,可增加红色框线或者文字备注说明。 - -图片写作示例: - - 图片以 ![](./figures/pic_name.png) 格式书写,“./” 不可少,否则图片无法显示到现网。 - -## 代码块 - -代码示例说明了如何实现特定功能,开发人员使用代码示例来编写和调试代码。代码要求如下: - -- 代码的逻辑和语法正确。 -- 代码的输入和输出尽可能的分开。 -- 保证代码中关键步骤要有注释说明。 -- 代码源于具体实例。 -- 文中行内代码和命令行使用 1 对反引号 如: `代码行`。 -- 块级代码使用 3 个顿号或 4 个空格(不能用 TAB 键)缩进,且上下均用整行隔开,如下: - - ```python - #!/usr/bin/env python3 - print("Hello, World!"); - ``` - - ```c - #include - int main(void) - { - printf("Hello world\n"); - } - ``` - -## 列表 - -使用列号 “1.” 或者 “*”,其后内容空格隔开,示例如下: - - 1. 一层列表 - 2. 一层列表 - 3. 一层列表 - * 二层列表 - * 二层列表 - -列表内标点符号使用规则: - -1. 当项目列表是术语、短语时,统一不加标点符号。 -2. 当项目列表是句子时,统一加句号。 -3. 特殊情况下如果不能避免出现短语和句子混合的情况,统一加句号。 -4. 项目列表前几项以分号结尾,最后一项以句号结尾的形式也可以接受。 - -## 注释符号 - -文档中会出现以下注释符号,代表不同的使用场景和提示程度。如果需要提示用户注意的信息,可以根据重要程度选择对应的注释符号。 -![image](figures/SafetyAlert.png) - -## 链接 - -链接需要确保指向的目标文件存在,否则会造成链接跳转不正常,不建议使用 HTML 的链接样式。 - -链接示例: - - 这是一个链接 [菜鸟教程](https://www.runoob.com)。 - -## 表格 - -Markdown 文档中请使用以下方式创建表格,不建议使用 HTML 的表格样式。 - - | 表头 | 表头 | - | ---- | ---- | - | 单元格 | 单元格 | - | 单元格 | 单元格 | - -单元格内标点符号使用规则: - -1. 当表格内一列全部是术语、短语时,统一不加标点符号。 -2. 当表格内一列全部是句子时,统一加句号。 -3. 特殊情况下如果不能避免出现短语和句子混合的情况,统一加句号。 - -## 常用词汇 - -| 不建议使用 | 建议使用 | -| ---- | ---- | -| 阀值 | 阈值 | -| 登陆 | 登录 | - -## 标点符号 - -- 单位与数字之间不建议加空格,比如 50m,10kg,64Kbit/s。 -- 对于有序/无序列表,如果是长句子,建议统一以句号结尾,如果是短语,结尾可不用标点。**重点是前后一致,要么都加,要么都不加**。 -- 中文文档使用全角标点。 -- 数字使用半角字符。 -- 感叹号使用场景为可能引发严重后果的操作或设备安全、人身安全的警告。其他场景不允许使用感叹号。 -- 文内引用其他文档件事添加书名号,同时建议增加引用文档的跳转链接。例如:安装 openEuler 系统,安装方法参考《[openEuler 22.03 LTS SP2 安装指南](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/Installation/installation.html)》。 - -## docs 仓库提交 PR 和 issue - -1. PR 规范 - - - PR 标题清晰易懂,内容描述详细具体,一个 PR 只包含一次提交(git log,git reset commit id , git push -f),一个 PR 只涉及一个主题修改。 - - 需要 2 个回复 /lgtm,1 个 /approve,一般需要需求提出或文档相关责任人进行审核。 - - CI 格式检查成功,需要满足无 markdownlint 报错。 - - PR 需要关联 issue,每个特性需求 /bug 都要转 issue 跟踪,并关联对应版本号。 - - 新增文档需要同步修改目录文件 menu.json 文件。 - - 对于同步维护的分支,PR 需要分别提交到对应分支上。 - -2. issue 规范 - -有文档需要合入需要先新建 issue,内容表述清晰即可,如果是 bug 需要指出具体哪个版本哪本文档需要修改。 - -3. PR 提交建议 - - - 修改同一类问题(例如末尾句号)建议全文一致,不仅仅修改一处。 - - 建议将同一篇文档的低错问题修改条在一个 PR 里。 - - 建议在评论区使用 /sync + 版本号的方式将当前 PR 修改同步到其它分支。 - -4. 文档贡献中不受欢迎的行为 - -短时间内通过自动化工具,提交大量的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)。 - -## 资料PR检视Checklist - -- **规范和低错类**问题 - - 错别字或拼写错误;标点符号使用错误 - - 链接错误、空单元格、格式错误 - - 英文中包含中文字符 - - 界面和描述不一致,但不影响操作 - - 表述不通顺,但不影响理解 - - 版本号不匹配:如软件包名称、界面版本号 - - 相同内容在同一文档中写法不一致 - - 软件名称书写不规范 - - 描述口语化 - - 图形、表格不符合规范 - - 专有名词的写作不符合业界规范或拼写错误。 - - 成双成对的标点符号使用过程中有缺失另一半,或使用不规范 - - 标题和正文中,命令的大小写写法不一致 - - 图片不显示、超大,超出正文或页面宽度、变形、缺失或冗余 - - 命令解释和命令写在一起 - - 相同内容在同一个地方重复描述 - - 操作截图与实际环境不一致 - - 步骤中命令行和回显中的命令行不一致 -- **易用性**问题 - - 关键步骤错误或缺失,无法指导用户完成任务 - - 缺少必要的前提条件、注意事项等 - - 操作场景不明确 - - 图形、表格、文字等晦涩难懂 - - 逻辑不清晰,该分类、分项、分步骤的没有给出 - - 步骤不易理解和学习,如命令缺少描述 - - 已明确说明不支持的场景,又给了该场景下的使用方法或约束 - - 文档名称不规范,根据文档名称不能快速定位手册描述重点 - - 步骤描述和实际的操作不符 -- **正确性**问题 - - 技术原理、功能、规格、配套版本、OS 等描述和软件不一致,存在错误 - - 原理图、架构图等存在错误 - - 命令、命令参数、IP等错误 - - 命令无法完成对应功能 - - 界面错误,无法指导操作 - - 链接本来就是错误的,跳转的版本或内容不正确 - - 链接未失效,但是所需内容已更新不存在 - - 代码格式不规范,如未换行,或缩进不正确,括号没有匹配等 - - 命令行中有多余的空格,导致命令报错 -- **风险提示**问题 - - 对重要数据或系统存在风险的操作,缺少安全提示 -- **合规**问题 - - 违反法律法规,涉及政治、领土主权等敏感词 - - 内容侵权 - -## 参考 - -您如需获取更多写作技巧,请参考 [Markdown常用语法参考](./MarkDown常用语法参考.md)和[markdownlint检查规则](./markdownlint检查规则.md)。 diff --git a/docs/zh/Cloud/ClusterDeployment/_menu.md b/docs/zh/Cloud/ClusterDeployment/_menu.md deleted file mode 100644 index 502a6ca6d0d6f1d69766aa566ccb7f074c9e2135..0000000000000000000000000000000000000000 --- a/docs/zh/Cloud/ClusterDeployment/_menu.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -label: '集群部署' -children: - - reference: './Kubernetes/_menu.md' - - reference: './iSulad+k8s/_menu.md' ---- \ No newline at end of file diff --git a/docs/zh/Cloud/ContainerEngine/_menu.md b/docs/zh/Cloud/ContainerEngine/_menu.md deleted file mode 100644 index 7acf74fd2e7f7c09ccdaa1efe61748f0d0f6b137..0000000000000000000000000000000000000000 --- a/docs/zh/Cloud/ContainerEngine/_menu.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -label: '容器引擎' -children: - - reference: './iSulaContainerEngine/_menu.md' - - reference: './DockerEngine/_menu.md' ---- \ No newline at end of file diff --git a/docs/zh/Cloud/ContainerForm/_menu.md b/docs/zh/Cloud/ContainerForm/_menu.md deleted file mode 100644 index 6fe128659f1709bb0bcd3ccdab9bc428d36aee6e..0000000000000000000000000000000000000000 --- a/docs/zh/Cloud/ContainerForm/_menu.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -label: '容器形态' -children: - - reference: './SecureContainer/_menu.md' - - reference: './SystemContainer/_menu.md' ---- \ No newline at end of file diff --git a/docs/zh/Cloud/ContainerRuntime/_menu.md b/docs/zh/Cloud/ContainerRuntime/_menu.md deleted file mode 100644 index 8d7d8906812114793f87cdbd66c5d08f8d1cee0c..0000000000000000000000000000000000000000 --- a/docs/zh/Cloud/ContainerRuntime/_menu.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -label: '容器运行时' -children: - - reference: './Kuasar/_menu.md' ---- \ No newline at end of file diff --git a/docs/zh/Cloud/HybridDeployment/_menu.md b/docs/zh/Cloud/HybridDeployment/_menu.md deleted file mode 100644 index 10643406dac1fcb9b7687c6c6565e0ad88e1c357..0000000000000000000000000000000000000000 --- a/docs/zh/Cloud/HybridDeployment/_menu.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -label: '混合部署' -children: - - reference: './rubik/_menu.md' - - reference: './oncn-bwm/_menu.md' ---- \ No newline at end of file diff --git a/docs/zh/Cloud/ImageBuilder/_menu.md b/docs/zh/Cloud/ImageBuilder/_menu.md deleted file mode 100644 index 68124f3bc2ca5d8e19a40a0ccb86bc05fee5ee89..0000000000000000000000000000000000000000 --- a/docs/zh/Cloud/ImageBuilder/_menu.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -label: '容器镜像构建工具' -children: - - reference: './isula-build/_menu.md' ---- \ No newline at end of file diff --git a/docs/zh/Cloud/Kmesh/_menu.md b/docs/zh/Cloud/Kmesh/_menu.md deleted file mode 100644 index 29face3a2ad58db62258ed942a16ef967bf50676..0000000000000000000000000000000000000000 --- a/docs/zh/Cloud/Kmesh/_menu.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -label: '服务网格' -children: - - reference: './Kmesh/_menu.md' ---- \ No newline at end of file diff --git a/docs/zh/Cloud/KubeOS/_menu.md b/docs/zh/Cloud/KubeOS/_menu.md deleted file mode 100644 index a2d2ca2723e3ff59decc82451b6db0a12bf64baf..0000000000000000000000000000000000000000 --- a/docs/zh/Cloud/KubeOS/_menu.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -label: '云原生操作系统' -children: - - reference: './KubeOS/_menu.md' ---- \ No newline at end of file diff --git a/docs/zh/Cloud/NestOS/_menu.md b/docs/zh/Cloud/NestOS/_menu.md deleted file mode 100644 index eed93bead26d6153259fec31dbd0574690cfe6c8..0000000000000000000000000000000000000000 --- a/docs/zh/Cloud/NestOS/_menu.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -label: '云底座操作系统' -children: - - reference: './NestOS/_menu.md' ---- \ No newline at end of file diff --git a/docs/zh/Cloud/_menu.md b/docs/zh/Cloud/_menu.md index 8dc6857a4719b54cc8316cbcef6c91d87d127f77..386ce70fc48b9cdd16244bd0e435529560ce33f1 100644 --- a/docs/zh/Cloud/_menu.md +++ b/docs/zh/Cloud/_menu.md @@ -1,13 +1,35 @@ --- label: '云原生' children: - - reference: './ContainerEngine/_menu.md' - - reference: './ContainerForm/_menu.md' - - reference: './ContainerRuntime/_menu.md' - - reference: './ImageBuilder/_menu.md' - - reference: './KubeOS/_menu.md' - - reference: './NestOS/_menu.md' - - reference: './HybridDeployment/_menu.md' - - reference: './ClusterDeployment/_menu.md' - - reference: './Kmesh/_menu.md' ---- \ No newline at end of file + - label: '容器引擎' + children: + - reference: './ContainerEngine/iSulaContainerEngine/_menu.md' + - reference: './ContainerEngine/DockerEngine/_menu.md' + - label: '容器形态' + children: + - reference: './ContainerForm/SecureContainer/_menu.md' + - reference: './ContainerForm/SystemContainer/_menu.md' + - label: '容器运行时' + children: + - reference: './ContainerRuntime/Kuasar/_menu.md' + - label: '容器镜像构建工具' + children: + - reference: './ImageBuilder/isula-build/_menu.md' + - label: '云原生操作系统' + children: + - reference: './KubeOS/KubeOS/_menu.md' + - label: '云底座操作系统' + children: + - reference: './NestOS/NestOS/_menu.md' + - label: '混合部署' + children: + - reference: './HybridDeployment/rubik/_menu.md' + - reference: './HybridDeployment/oncn-bwm/_menu.md' + - label: '集群部署' + children: + - reference: './ClusterDeploymen/Kubernetes/_menu.md' + - reference: './ClusterDeploymen/iSulad+k8s/_menu.md' + - label: '服务网格' + children: + - reference: './Kmesh/Kmesh/_menu.md' +---