From 2dfd9dce6cbad0fb476067b0a8f7ad51ab5683f7 Mon Sep 17 00:00:00 2001 From: chopupu <1123478123@qq.com> Date: Tue, 4 Mar 2025 20:48:45 +0800 Subject: [PATCH] =?UTF-8?q?menu=20=E6=96=87=E4=BB=B6=E6=95=B4=E5=90=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit update 写作规范 update 写作规范 update update update update --- ...55\346\263\225\345\217\202\350\200\203.md" | 140 ------- contribute/_menu.md | 12 +- contribute/ci_rules.md | 83 ++++ .../documentation_writing_specifications.md | 356 +++++++++++++++--- .../markdownlint_rules.md | 2 +- .../markdownlint_tools.md | 0 .../public_sys-resources/icon-caution.gif | Bin 0 -> 580 bytes .../public_sys-resources/icon-danger.gif | Bin 0 -> 580 bytes contribute/public_sys-resources/icon-note.gif | Bin 0 -> 394 bytes .../public_sys-resources/icon-notice.gif | Bin 0 -> 406 bytes contribute/public_sys-resources/icon-tip.gif | Bin 0 -> 253 bytes .../public_sys-resources/icon-warning.gif | Bin 0 -> 580 bytes ...31\344\275\234\350\247\204\350\214\203.md" | 302 --------------- docs/zh/Cloud/ClusterDeployment/_menu.md | 6 - docs/zh/Cloud/ContainerEngine/_menu.md | 6 - docs/zh/Cloud/ContainerForm/_menu.md | 6 - docs/zh/Cloud/ContainerRuntime/_menu.md | 5 - docs/zh/Cloud/HybridDeployment/_menu.md | 6 - docs/zh/Cloud/ImageBuilder/_menu.md | 5 - docs/zh/Cloud/Kmesh/_menu.md | 5 - docs/zh/Cloud/KubeOS/_menu.md | 5 - docs/zh/Cloud/NestOS/_menu.md | 5 - docs/zh/Cloud/_menu.md | 42 ++- 23 files changed, 417 insertions(+), 569 deletions(-) delete mode 100644 "contribute/MarkDown\345\270\270\347\224\250\350\257\255\346\263\225\345\217\202\350\200\203.md" create mode 100644 contribute/ci_rules.md rename "contribute/markdownlint\346\243\200\346\237\245\350\247\204\345\210\231.md" => contribute/markdownlint_rules.md (99%) rename "contribute/markdownlint\351\224\231\350\257\257\344\277\256\345\244\215\345\267\245\345\205\267.md" => contribute/markdownlint_tools.md (100%) create mode 100644 contribute/public_sys-resources/icon-caution.gif create mode 100644 contribute/public_sys-resources/icon-danger.gif create mode 100644 contribute/public_sys-resources/icon-note.gif create mode 100644 contribute/public_sys-resources/icon-notice.gif create mode 100644 contribute/public_sys-resources/icon-tip.gif create mode 100644 contribute/public_sys-resources/icon-warning.gif delete mode 100644 "contribute/\345\206\231\344\275\234\350\247\204\350\214\203.md" delete mode 100644 docs/zh/Cloud/ClusterDeployment/_menu.md delete mode 100644 docs/zh/Cloud/ContainerEngine/_menu.md delete mode 100644 docs/zh/Cloud/ContainerForm/_menu.md delete mode 100644 docs/zh/Cloud/ContainerRuntime/_menu.md delete mode 100644 docs/zh/Cloud/HybridDeployment/_menu.md delete mode 100644 docs/zh/Cloud/ImageBuilder/_menu.md delete mode 100644 docs/zh/Cloud/Kmesh/_menu.md delete mode 100644 docs/zh/Cloud/KubeOS/_menu.md delete mode 100644 docs/zh/Cloud/NestOS/_menu.md 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 f2f4a6098..000000000 --- "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 82d53c7bf..456b5577c 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 000000000..4d59ad3ae --- /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 1107ada60..63c2911f5 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 d7a8cf07d..2dc12ff94 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 GIT binary patch literal 580 zcmV-K0=xZ3Nk%w1VIu$?0Hp~4{QBgqmQ+MG9K51r{QB&)np^||1PlfQ%(86!{`~yv zv{XhUWKt}AZaiE{EOcHp{O-j3`t;<+eEiycJT4p@77X;(jQsMfB$R?oG%6hQ z+MMLZbQBH@)Vg&1^3?qHb(5!%>3r0+`eq=&V&E}0Dypi0000000000 z00000A^8LW000R9EC2ui03!e$000L5z=Uu}ED8YtqjJd<+B}(9bIOb$3-31_h|V>=0A{ z1Hh0#H30>fNT})^fRU_83uewx9oRr{f{Sx1Ml`t)EQ zGkHZ67&~y{W5Jpq4H_WfuLxp*3<7O}GEl;1ESe36fLNs=B0&LQM1Buf(R)qg(BRd`t1OPjI1m_q4 literal 0 HcmV?d00001 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 GIT binary patch literal 580 zcmV-K0=xZ3Nk%w1VIu$?0Hp~4{QBgqmQ+MG9K51r{QB&)np^||1PlfQ%(86!{`~yv zv{XhUWKt}AZaiE{EOcHp{O-j3`t;<+eEiycJT4p@77X;(jQsMfB$R?oG%6hQ z+MMLZbQBH@)Vg&1^3?qHb(5!%>3r0+`eq=&V&E}0Dypi0000000000 z00000A^8LW000R9EC2ui03!e$000L5z=Uu}ED8YtqjJd<+B}(9bIOb$3-31_h|V>=0A{ z1Hh0#H30>fNT})^fRU_83uewx9oRr{f{Sx1Ml`t)EQ zGkHZ67&~y{W5Jpq4H_WfuLxp*3<7O}GEl;1ESe36fLNs=B0&LQM1Buf(R)qg(BRd`t1OPjI1m_q4 literal 0 HcmV?d00001 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 GIT binary patch literal 394 zcmZ?wbhEHblx7fPSjxcg=ii?@_wH=jwxy=7CMGH-B`L+l$wfv=#>UF#$gv|VY%C^b zCQFtrnKN(Bo_%|sJbO}7RAORe!otL&qo<>yq_Sq+8Xqqo5h0P3w3Lvb5E(g{p01vl zxR@)KuDH0l^z`+-dH3eaw=XqSH7aTIx{kzVBN;X&hha0dQSgWuiw0NWUvMRmkD|> literal 0 HcmV?d00001 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 GIT binary patch literal 406 zcmV;H0crk6Nk%w1VIu$@0J8u9|NsB@_xJDb@8;&_*4Ea}&d#;9wWXz{jEszHYim+c zQaU<1At50E0000000000A^8Le000gEEC2ui03!e%000R7038S%NU)&51O^i-Tu6`s z0)`MFE@;3YqD6xSC^kTNu_J>91{PH8XfZ(p1pp2-SU@u3#{mEUC}_}tg3+I#{z}{Ok@D_ZUDg- zt0stin4;pC8M{WLSlRH*1pzqEw1}3oOskyNN?j;7HD{BBZ*OEcv4HK!6Bk6beR+04 z&8}k>SkTusVTDmkyOz#5fCA$JTPGJVQvr3uZ?QzzPQFvD0rGf_PdrcF`pMs}p^BcF zKtKTd`0wipR%nKN&Wj+V}pX;WC3SdJV!a_8Qi zE7z`U*|Y^H0^}fB$R?oG%6hQ z+MMLZbQBH@)Vg&1^3?qHb(5!%>3r0+`eq=&V&E}0Dypi0000000000 z00000A^8LW000R9EC2ui03!e$000L5z=Uu}ED8YtqjJd<+B}(9bIOb$3-31_h|V>=0A{ z1Hh0#H30>fNT})^fRU_83uewx9oRr{f{Sx1Ml`t)EQ zGkHZ67&~y{W5Jpq4H_WfuLxp*3<7O}GEl;1ESe36fLNs=B0&LQM1Buf(R)qg(BRd`t1OPjI1m_q4 literal 0 HcmV?d00001 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 4c9566d4c..000000000 --- "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 502a6ca6d..000000000 --- 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 7acf74fd2..000000000 --- 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 6fe128659..000000000 --- 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 8d7d89068..000000000 --- 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 10643406d..000000000 --- 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 68124f3bc..000000000 --- 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 29face3a2..000000000 --- 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 a2d2ca272..000000000 --- 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 eed93bead..000000000 --- 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 8dc6857a4..386ce70fc 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' +--- -- Gitee