快速入门 ​

概述 ​

openEuler 文档采用 Markdown 格式编写，通过 Git 进行版本管理，托管于 Gitee 平台，文档修改通过 Pull Request（PR）工作流进行审核与合并。openEuler 文档分仓存储，《发行说明》、《安装指南》、《升级指南》等基础特性文档存在 openEuler/docs 仓，由 DOC SIG 维护。《A-Tune 用户指南》等增量特性文档分别存在各特性代码仓，由各特性 SIG 组维护。

文档中心将手册按业务场景和工具模块分类，常见的文档开发场景如下：

• 新增场景：需联系 DOC SIG maintainer 修改。
• 新增手册：新增功能特性时，需在对应场景下新增特性手册，除了需要在特性代码仓维护文档内容外，还需要配置 openeuler/docs 仓对应场景的 _toc.yaml 文件。
• 修改手册：包括低错问题修复、章节增删等内容调整，直接在对应代码仓中更新文档即可。

快速开始 ​

下面以服务器场景 openEuler 24.03 LTS SP2 版本的《oeAware用户指南》的修改为例，介绍如何进行文档开发。

准备仓库 ​

需准备两个仓库：

• openeuler/docs：文档总仓库，通过引用机制，集成所有特性文档至文档中心。
• openeuler/oeAware-manager：oeAware 特性源码仓，存储《oeAware用户指南》源文档。

1. 准备 openeuler/docs 仓

   (1) Fork openeuler/docs 仓。

   找到并打开对应的Repository的首页。点击右上角的Fork按钮，按照指引，建立一个属于个人的云上 fork 仓库。

   (2) 克隆 openeuler/docs 仓库。

   克隆 fork 仓库到本地，并将本地仓库与远程仓库关联。

   bash

   git clone https://gitee.com/wu-donger/docs.git
   
   cd docs
   git remote add upstream https://gitee.com/openeuler/docs.git
   git fetch upstream

   (3) 切换分支。

   依据所需修改文档的版本，切换到对应的分支。通常情况下，分支命名规则为stable-版本号。此处以25.03版本为例。

   bash

   git checkout -b work2403sp2 upstream/stable-24.03_LTS_SP2

2. 准备 openeuler/oeAware-manager 仓

   找到并打开源码仓的Repository的首页。fork 仓库并克隆 fork 仓库到本地，切换目标分支。

   bash

   git clone https://gitee.com/wu-donger/oeAware-manager.git
   
   cd oeAware-manager
   git remote add upstream https://gitee.com/openeuler/oeAware-manager.git
   git fetch upstream
   
   git checkout -b workmaster upstream/master

文档变更 ​

新增手册 ​

1. 明确目标仓库

   若首次添加特性指南时需明确：

   • 源文档存放仓库：特性源码仓库。
   • 版本策略：通过分支或目录管理版本（推荐分支方式）。

   示例：《oeAware用户指南》源文档存放仓库是 oeAware 特性的源码仓 openeuler/oeAware-manager，通过目录区分 openEuler 版本。

   相关约束和要求详见SIG 组文档目录结构规范。

   此外，需为目标仓库配置文档 ci 和文档检视人员，可联系 DOC SIG maintainer 操作。

2. 创建文件夹

   openEuler 的文档按照一定的目录结构组织，新增手册需要为其创建一个文件夹，存放实际内容文件和目录结构文件。《oeAware用户指南》的存放位置如下：

   text

   ├─openeuler/oeAware-manager 仓
   ├─docs
   |  ├─en
   |  └─zh
   |    └─2403_lts_sp2                                             # 版本：openEuler 24.03 LTS SP2
   |           ├─oeawrae_user_guide.md                             # 文档内容文件
   |           └─_toc.yaml                                         # 文档目录结构文件

   说明 在仓库根目录下创建 /docs 目录，并在 /docs 目录下创建 zh/ 和 en/ 目录存放需发布至官网的中英文文档。

3. 编辑目录结构文件_toc.yaml

   在步骤 1 所创建的文件夹中，新建一个_toc.yaml文件，以维护手册内各章节的展示逻辑。

   yaml

   label: oeAware用户指南                                     # 手册名：《oeAware用户指南》
   isManual: true                                            # isManual：标识此文件是手册的目录结构文件
   description: 动态感知系统行为后，智能使能系统的调优特性       # 手册简介
   sections:
     - label: 使用oeAware                                    # 章节名：使用oeAware 
       href: ./oeaware_user_guide.md                         # 文档源文件地址

4. 关联手册至对应场景

   在 openeuler/docs 仓服务器场景的 _toc.yaml 文件中，添加对《oeAware用户指南》的引用。

   yaml

   label: 服务器                                                                                                   # 场景名：服务器
   sections: 
     - label: 性能调优                                                                                             # 一级目录：性能调优 
       sections:
         - label: 概述                                                                                             # 二级目录：概述
           sections:
             - href: ./performance/overall/system_resource/_toc.yaml
         - label: 调优框架                                                                                          # 二级目录：调优框架 
           sections:
             - href:                                                                                               
                 upstream: https://gitee.com/openeuler/oeAware-manager/blob/master/docs/zh/2403_lts_sp2/_toc.yaml  # 手册：《oeAware用户指南》
                 path: ./performance/tuning_framework/oeaware                                                      # 手册的url访问路径

修改文档 ​

以在《oeAware用户指南》中增加“认识oeAware”章节为例，首先在《oeAware用户指南》的存放目录下，新增文档内容文件getting_to_konw_oeaware.md，并在《oeAware用户指南》的 _toc.yaml 下，增加对getting_to_konw_oeaware.md的引用：

label: oeAware用户指南                                     # 手册名：《oeAware用户指南》
isManual: true                                            # isManual：标识此文件是手册的目录结构文件
description: 动态感知系统行为后，智能使能系统的调优特性       # 手册简介
sections:
  - label: 认识oeAware                                    # 章节名：认识oeAware
    href: ./getting_to_konw_oeaware.md                    # 新增的文档源文件地址
  - label: 使用oeAware                                    # 章节名：使用oeAware 
    href: ./oeaware_user_guide.md                         # 文档源文件地址

提交变更 ​

1. 提交 openeuler/docs 仓的文档变更。

   （1）提交变更并push到远程仓库。

   bash

   git add .
   
   git commit -m "提交原因"
   
   git push origin work2403sp2

   （2）创建PR。

   在个人文档仓 Pull Requests 页面 https://gitee.com/{your_org}/docs/pulls，点击新建Pull Request创建PR。源分支选择 {your_org}/docs/work2403sp2，目的分支选择 openeuler/docs/stable-24.03_LTS_SP2。填写该PR的标题，并对修改内容进行简要说明，点击创建Pull Request。

   （3）合入PR。

   合入条件：文档流水线门禁通过，cla已签署，DOC SIG maintainer检视通过。

   

2. 提交 openeuler/oeaware-manager 仓的文档变更。

   （1）提交变更并push到远程仓库并创建 PR。

   （2）合入PR。

   合入条件：SIG 组代码仓涉及文档变更的 PR，除代码仓原有的合入条件外，还需要文档流水线门禁通过，DOC SIG maintainer检视通过。

   

   说明

   DOC SIG maintainer 检视通过前会审视此 PR 是否需要转测试验收，检视测试流程详见：文档检视测试流程。

3. 英文翻译

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

更多 ​

了解更多细节和进阶内容 ​

• 了解 openEuler 文档组织架构
• 了解 markdown 写作规范
• 了解 开源社区贡献流程