diff --git a/docs/zh/contribute/contribution_process.md b/docs/zh/contribute/contribution_process.md index 2e3c7c61b39bd2ba7a3aff4382c274fee922acfa..3b743af5df791fd2052575127123aee65040b5fd 100644 --- a/docs/zh/contribute/contribution_process.md +++ b/docs/zh/contribute/contribution_process.md @@ -178,7 +178,7 @@ sections: ![image](figures/sigdoc_approve.png) > [!NOTE]说明 - > DOC SIG maintainer 审核通过前会审视此 PR 是否需要转测试验收，检视测试流程详见：[文档检视测试流程](https://gitee.com/openeuler/docs/blob/stable-common/docs/zh/contribute/doc_review_test_process.md)。 + > DOC SIG maintainer 审核通过前会审视此 PR 是否需要转测试验收，检视测试流程详见：[文档检视测试流程](./directory_structure_introductory.md#文档检视测试流程)。 3. 英文翻译 diff --git a/docs/zh/contribute/directory_structure_introductory.md b/docs/zh/contribute/directory_structure_introductory.md index 0138a849b82a70dbdca0a99c3c677f401ac7326b..49fe12e63494c7ac1ff04c5db31b7498dd0f54d5 100644 --- a/docs/zh/contribute/directory_structure_introductory.md +++ b/docs/zh/contribute/directory_structure_introductory.md @@ -259,7 +259,8 @@ SIG 组文档/源码仓库仅存放特性手册，《oeAware用户指南》的 | └─en/ ``` - > [!NOTE]说明 存放于 docs/zh 和 docs/en 下的文档均为发布至官网文档中心的文档，必须通过文档流水线，才能合入；若文档仅在仓库内展示、无需发布至官网，不可存放于上述目录，可在 docs/ 下创建其他目录存放。 + > [!NOTE]说明 + > 存放于 docs/zh 和 docs/en 下的文档均为发布至官网文档中心的文档，必须通过文档流水线，才能合入；若文档仅在仓库内展示、无需发布至官网，不可存放于上述目录，可在 docs/ 下创建其他目录存放。 - 在 openeuler/docs 仓库中，找到对应场景的 _toc.yaml 文件，并按照指定格式添加文档的索引地址： @@ -449,12 +450,41 @@ sections: - label：场景名称。 - description：场景的简介说明。 - sections： - - label： 一级目录名称。 + - label：一级目录名称。 - sections： - href：手册的目录配置文件引用。 - upstream（仅增量特性文档）：增量特性手册的目录配置文件引用。 - path（仅增量特性文档）：手册的url访问路径（可选，默认值是“./仓库名”）。 +## 文档检视测试流程 + +为保障文档质量，确保其得到充分检视与完备测试，建议各SIG组遵循以下流程。 + +![image](figures/检视测试流程发布.jpg) + +**版本发布之前**： + +1. 版本关键角色，根据版本需求，确定文档清单和交付计划，Doc SIG Maintainer 跟踪版本文档需求交付进展； +2. openeuler/docs 仓拉取新分支； +3. 代码仓拉取新分支； +4. 特性 owner 贡献文档，提 PR； +5. 特性 SIG Maintainer 检视文档； +6. 文档工程师检视文档，转测试； +7. 测试工程师检视文档； +8. 特性 owner 修改 PR 意见； +9. 特性 SIG Maintainer 合入文档。 + +**版本发布之后**： + +1. 用户使用文档之后，发现文档问题； +2. 提交文档 Issue（基础特性文档提到 docs 仓，增量特性文档提到各个 SIG 组代码仓；如果提到 docs 仓，则由 Doc SIG maintainer 转到对应代码仓）； +3. 特性 owner 处理 Issue，提交文档 PR； +4. SIG Maintainer 检视文档； +5. 文档工程师检视文档，如仅低错修改，无需转测试；如涉及实际内容修改，则转测试（每周或双周固定时间转测试，与 update 版本 Issue 转测节奏保持一致）； +6. 测试工程师检视文档； +7. 特性 owner 修改 PR 意见； +8. SIG Maintainer 合入文档。 + ## 文档存放地址 openEuler 文档存储于 [openEuler/docs](https://gitee.com/openeuler/docs) 仓和各 SIG 的文档/源码仓。以下为您提供每本手册在文档仓中的具体存放地址。 @@ -545,7 +575,7 @@ openEuler 文档存储于 [openEuler/docs](https://gitee.com/openeuler/docs) 仓 secGear开发指南 - openeuler/secGear/docs/zh/2403_LTS_SP2 + openeuler/secGear/docs/zh/2403_LTS_SP2 CVE-ease设计指南 @@ -561,7 +591,7 @@ openEuler 文档存储于 [openEuler/docs](https://gitee.com/openeuler/docs) 仓 secDetector使用指南 - openeuler/secDetector/docs/zh/2403_LTS_SP2 + openeuler/secDetector/docs/zh/2403_LTS_SP2 内存与存储 @@ -696,7 +726,7 @@ openEuler 文档存储于 [openEuler/docs](https://gitee.com/openeuler/docs) 仓 容器镜像构建工具 容器镜像构建 - openeuler/cloudnative-docs/docs/zh/image_builder/isula-build + openeuler/cloudnative-docs/docs/zh/image_builder/isula-build 云原生操作系统 @@ -715,7 +745,7 @@ openEuler 文档存储于 [openEuler/docs](https://gitee.com/openeuler/docs) 仓 oncn-bwm用户指南 - openeuler/cloudnative-docs/docs/zh/hybrid_deployment/oncn-bwm + openeuler/cloudnative-docs/docs/zh/hybrid_deployment/oncn-bwm 集群部署 @@ -724,7 +754,7 @@ openEuler 文档存储于 [openEuler/docs](https://gitee.com/openeuler/docs) 仓 iSulad+k8s集群部署指南 - openeuler/cloudnative-docs/docs/zh/cluster_deployment/isulad+k8s + openeuler/cloudnative-docs/docs/zh/cluster_deployment/isulad+k8s 服务网格 @@ -771,7 +801,7 @@ openEuler 文档存储于 [openEuler/docs](https://gitee.com/openeuler/docs) 仓 UniProton用户指南 - openeuler/UniProton/docs/zh + openeuler/UniProton/docs/zh @@ -881,6 +911,6 @@ openEuler 文档存储于 [openEuler/docs](https://gitee.com/openeuler/docs) 仓 安全 / secGear开发指南 - openeuler/secGear/docs/zh/2403_LTS_SP2 + openeuler/secGear/docs/zh/2403_LTS_SP2 diff --git a/docs/zh/contribute/doc_tools_functions.md b/docs/zh/contribute/doc_tools_functions.md index 72a95f2573cd2f04169c0f54e4af2acab11eafb3..bb382e491f289b21d494ad6b623bb9dfb4808a91 100644 --- a/docs/zh/contribute/doc_tools_functions.md +++ b/docs/zh/contribute/doc_tools_functions.md @@ -95,7 +95,8 @@ ### 功能介绍 -- 将选中的文本生成锚点并复制到剪贴板，方便后续使用。 +- 将选中的文本生成锚点并复制到剪贴板，方便后续使用； +- 生成的锚点遵循以下规范：字母转换为小写，空格替换为中划线，并移除特殊符号（如`!`，`*`）。 ### 使用方法 @@ -106,5 +107,5 @@ ### 注意事项 -- 生成的锚点适用于 Vitepress 页面的锚点跳转； +- 生成的锚点适用于 Vitepress 页面，VSCode 编辑器，以及 Gitee 仓库的锚点跳转； - 通常情况下和大多数 Markdown 预览（如 VSCode 编辑器自带的 Markdown 预览）的锚点跳转一致，但在内容有一些符号的情况下存在一些差异，可能导致锚点在非 Vitepress 构建出的页面下不能跳转。 diff --git a/docs/zh/contribute/doc_tools_static_check.md b/docs/zh/contribute/doc_tools_static_check.md index e44127188320d9fa6c107b770ffd8e83cbc76e1a..25096b944c5be63fa5978fead58bebba9858a18e 100644 --- a/docs/zh/contribute/doc_tools_static_check.md +++ b/docs/zh/contribute/doc_tools_static_check.md @@ -94,14 +94,24 @@ ### 功能介绍 -- 自动扫描 [Markdown 文档中的所有链接](./ci_rules.md#link-validity-check)，包括以下三种格式： - - `[文本](链接)` 形式的标准 Markdown 链接 - - `` 形式的裸链接 - - `` 形式的 HTML 链接 -- 支持 HTTP/HTTPS 链接检测，自动忽略链接中的锚点部分（如 `#section`），仅校验主链接地址； -- 支持对相对路径的文件链接，进行本地文件存在性检查，并可检查锚点的有效性； -- 支持自定义 HTTP/HTTPS 链接检查白名单，避免对特定可信链接进行报错； -- 支持通过配置项灵活启用或禁用该功能。 +- 链接识别 + 支持自动识别文档中以下三种格式的链接： + 1. `[文本](链接)`形式的标准 Markdown 链接； + 2. ``形式的裸链接； + 3. ``形式的 HTML 链接。 +- 链接检查 + 1. 支持 HTTP/HTTPS 链接检测，自动忽略链接中的锚点部分（如`#section`），仅校验主链接地址； + 2. 支持对相对路径的文件链接，进行本地文件存在性检查，并可检查[锚点的有效性](./doc_tools_functions.md#生成链接锚点并复制)。 +- 白名单机制 + 支持配置 HTTP/HTTPS 链接检查白名单，避免对特定可信链接进行报错： + - 默认从远程配置文件中获取： + 1. 内网地址，如`http://localhost`，`http://192.168.1.60`； + 2. 邮件协议，文件协议，FTP文件协议链接如`ftp://`，`file://`； + 3. 示例链接，如`https://repo.openeuler.org/openEuler-{version}/OS/x86_64/`。 + - 支持按需自定义添加新的白名单。 +- 灵活配置 + 1. 支持通过配置项灵活启用或禁用该功能； + 2. 支持通过配置项启用“仅在链接响应为404（无法访问）时提示”的模式。 ### 使用方法 @@ -310,12 +320,15 @@ ### 功能介绍 -- 自动扫描 Markdown 文档中的文本内容，检测标点符号使用是否规范； -- 支持检查中英文标点符号混用问题，如中文文本中使用英文标点，或英文文本中使用中文标点； -- 支持检查中文标点符号前后空格使用规范，中文标点前后不应有空格； -- 支持检查标点符号是否存在连续使用的情况； -- 支持检查手册/指南链接是否被书名号包裹； -- 标点符号错误会在编辑器以提示（Info）的形式高亮显示，可在底部问题面板，或将光标悬停在错误标记处，查看错误详情。 +- 自动扫描 Markdown 文档中的文本内容，检测标点符号使用是否规范，包括以下检查项： + 1. 中文使用了英文符号：中文字段（代码样例等英文段落除外）使用英文标点符号； + 2. 多余标点符号：出现连续两个及以上标点符号； + 3. 多余空格：中文标点符号前后有空格； + 4. 多余空格：中文文字之间有空格； + 5. 成对标点符号不完整； + 6. 不符合链接规范：如手册类外链接的链接文字中缺少书名号； + 7. 多余空格：英文标点符号前有空格，或标点后有多于一个空格； + 8. 英文使用了中符号：英文字段使用中文标点符号。 - 支持通过配置项灵活启用或禁用相关功能。 ### 使用方法 @@ -340,7 +353,6 @@ - 类型：`boolean` - 说明：启用连续标点符号检查 - 默认：`false` - - `docTools.check.punctuationManualLink.enable` - 类型：`boolean` - 说明：启用手册/指南链接是否被书名号包裹检查 diff --git a/docs/zh/contribute/documentation_writing_specifications.md b/docs/zh/contribute/documentation_writing_specifications.md index b20f1e30e224a1fc3ed5aa449f1cad47b75e73bc..40aa69fbc713164ba64054c5e679c01378cec970 100644 --- a/docs/zh/contribute/documentation_writing_specifications.md +++ b/docs/zh/contribute/documentation_writing_specifications.md @@ -185,7 +185,7 @@ installation_and_deployment.md #新增‘安装与部署’文档 【规则】文中行内代码和命令行使用 1 对反引号，如： `代码块`。 -【规则】块级代码使用 3 个顿号或 4 个空格（不能用 TAB 键）缩进，且上下均用整行隔开。 +【规则】块级代码使用 3 个反引号或 4 个空格（不能用 TAB 键）缩进，且上下均用整行隔开。 【举例】 @@ -278,14 +278,43 @@ installation_and_deployment.md #新增‘安装与部署’文档 【规则】链接需要确保指向的目标文件存在，否则会造成链接跳转不正常，不建议使用 HTML 的链接样式。 +【规则】引用如果是某篇文档，建议用书名号包裹。 + 【举例】 ```markdown - 网站链接 -这是一个链接 [菜鸟教程](https://www.runoob.com)。 +A-Tune 的安装步骤请参考[《安装与部署》](https://www.atune.com)。 - 相对路径 - [文档开发流水线门禁](./ci_rules.md) +[文档开发流水线门禁](./ci_rules.md) +``` + +### 锚点 + +【规则】若要引用文档中的标题、图片或表格，可插入锚点，从而实现向文档特定位置的快速跳转。 + +【规则】锚点格式：将标题中大写字母转换为小写，空格替换为中划线`-`，并去除特殊符号。 + +【举例】 + +```markdown +# 安装前准备 A* + +这是A-Tune的安装前准备。 + +... + +参考[安装前准备](#安装前准备-a)章节。 +``` + +```markdown +**图1** CI 检查结果 +![CI 检查结果](./figures/ci检查结果.jpg) + +... + +参考图1[CI 检查结果](#fig1)。 ``` ### 表格 diff --git "a/docs/zh/contribute/figures/\346\243\200\350\247\206\346\265\213\350\257\225\346\265\201\347\250\213\345\217\221\345\270\203.jpg" "b/docs/zh/contribute/figures/\346\243\200\350\247\206\346\265\213\350\257\225\346\265\201\347\250\213\345\217\221\345\270\203.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..a39c7a804bb27862335899879dba3b3f406508a1 Binary files /dev/null and "b/docs/zh/contribute/figures/\346\243\200\350\247\206\346\265\213\350\257\225\346\265\201\347\250\213\345\217\221\345\270\203.jpg" differ