文档生产下沉至SIG组 ​

重要事项 ​

• 文档生产下沉至各 SIG 组后，各 SIG 组需重视文档质量，更新内容时请通知 doc-sig 成员检视（测试人员测试），通过后再合入。
• 文件名和文件夹名请使用英文小写字母、并用下划线连接（同一篇文档的中英文名保持一致），文档发布至官网后不可更改存放路径，如需更改需评审。

概述 ​

之前所有文档都集中存于 docs 仓。改版后，基础特性文档依旧存放在 docs 仓，由 doc-sig 集中管理，增量特性文档在各特性 SIG 的代码仓维护。分散在各特性代码仓的文档，需通过在 docs 仓的配置文件（_toc.yaml）中添加引用，实现发布至官网。

约束 ​

• 分版本写文档，openEuler 各版本均有独立配套文档。

• 文档发布后仍会持续更新，如修正低级错误、内容错漏等问题。

• 各 SIG 组负责维护特性文档，要求各 SIG 清晰掌握特性在各版本中的分布情况。

• 各 SIG 组自主规划文档，明确区分发布至官网的文档和仅在代码仓展示的文档。

• SIG 组维护文档以手册为最小单元（如服务器场景《A-Ops用户指南》），单本手册不得拆分存储，同一仓库可容纳多本手册。

• 所见即所得，在 gitee 仓库可直接查看文档内容，呈现效果与最终展示一致。

  

要求 ​

无论各 SIG 如何组织文档，如果文档要发布至官网，需要满足如下条件：

• 在仓库根目录下创建 docs 目录，并在 docs 目录下的 zh/ 和 en/ 目录中存放需发布至官网的中英文文档，结构如下：

  text

  ├─docs/
  |  ├─zh/
  |  └─en/

  注明：存放于 docs/zh 和 docs/en 下的文档均为发布至官网文档中心的文档，必须通过文档流水线，才能合入；若文档仅在仓库内展示、无需发布至官网，不建议存放于上述目录，可在 docs/ 下创建其他目录存放。

• 在 openeuler/docs 仓库中，找到对应场景的 _toc.yaml 文件，并按照指定格式添加文档的索引地址：

  upstream: 填写手册的目录结构文件（_toc.yaml）索引地址
  path（可选，默认值是“./仓库名”）: 设置手册的url访问路径

  示例：
  upstream: https://atomgit.com/openeuler/openstack-docs/blob/openEuler-25.03/docs/zh/_toc.yaml
  path: ./openstack

• 文档须严格对应当前版本特性，禁止包含未发布的特性或功能。

• 支持文档的长期更新维护，确保 openEuler 新版本发布后，历史版本文档仍保持准确完整。

方案 ​

为满足上述条件，建议的实现方案如下：

• 每个 SIG 组特性应该有自己的独立代码仓库，该仓库承载该SIG的特性文档、readme、contribute等内容。

• 在不同分支下维护对应版本的文档或创建目录维护不同版本的文档。

• 若选择创建目录维护不同版本的文档，其内容如下：

  text

  ├─docs/
  |  ├─zh/
  |  |  ├─2409/     
  |  |  |   ├─_toc.yaml     
  |  |  |   ├─xxx.md
  |  |  |   └─xxx/    
  |  |  |      └─xxx.md 
  |  |  └─2503/     
  |  |      ├─_toc.yaml     
  |  |      ├─xxx.md
  |  |      └─xxx/    
  |  |         └─xxx.md  
  |  └─en/  
  |     ├─2409/ 
  |     └─2503/

文档下沉流程 ​

1. SIG 组确定方案，明确文档存放仓库及版本区分方式。
2. 为仓库配置文档流水线和检视人员，请联系doc-sig。
3. 将相关文档从 openeuler/docs 仓库迁移至目标仓库。
4. 待 doc-sig 成员检视通过后，由SIG组自行安排合入。

英文翻译 ​

合入中文文档 PR 后，系统将自动生成翻译 issue 并排入处理队列，翻译人员会按顺序完成英文翻译并提交PR，需各 SIG 组 Maintainer 审核合入。如需加急翻译，请将对应中文文档 PR 链接同步至 doc-sig 协调优先处理。