快速入门 ​

概述 ​

本文档围绕新增文档，修改文档，删除文档三个任务场景，为开发者明确文档开发流程。

开发需要具备以下经验和技能：

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

通用流程 ​

首先，要明确待修改文档所在的仓库。可依据手册名称，定位对应的文档仓库及具体存放目录。下面以服务器场景《安装指南》的修改为例，介绍新增文档，修改文档，删除文档三个任务场景的通用流程。

1. 克隆仓库。

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

   bash

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

2. 切换分支。

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

   bash

   git fetch upstream
   
   git checkout stable2-25.03
   
   git rebase upstream/stable2-25.03
   
   git checkout -b work25.03

3. 提交变更。

   文档变更具体操作参考新增文档、修改文档、删除文档章节。

   bash

   git add .
   
   git commit -m "提交原因"

4. 合并到远程仓库，并创建 PR。

   bash

   git push origin work25.03

新增文档 ​

新增文档章节旨在指导开发者新增一本完整的手册。若要在现有手册中添加内容，比如在《升级指南》中增加“常用工具”章节，则参考修改文档。

以在服务器场景下新增《升级指南》为例，可参考以下操作步骤：

1. 创建存放文件夹

   首先确定《升级指南》的所属场景，进而找到其在文档仓的存放位置，在此处新建一个文件夹，用于存放该指南下所有的.md文件。

   text

   ├─docs
   |  ├─en
   |  └─zh
   |    └─Server                                                       # 场景：服务器
   |       └─InstallationUpgrade                                       # 一级目录：安装升级      
   |           ├─Installation                                          # 手册：《安装指南》
   |           └─Upgrade                                               # 新建文件夹：《升级指南》 
   |               ├─openEuler_22.03_LTS_upgrade_and_downgrade.md      # 文档内容文件 
   |               └─_toc.yaml                                         # 文档目录结构文件

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

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

   yaml

   label: 升级指南                                                # 手册名：《升级指南》
   isManual: true                                                # ismanual：标识此文件是手册的目录结构文件，与场景的目录结构文件作区分
   description: 升级 openEuler 操作系统                           # 手册简介
   sections:                                                        
     - label: 升降级指导                                          # 章节名：升降级指导
       href: ./openEuler_22.03_LTS_upgrade_and_downgrade.md      # 文档内容文件引用

3. 关联手册至对应场景

   在服务器场景的 _toc.yaml 文件中，添加对《升级指南》的引用。

   yaml

   label: 服务器                                                   # 场景名：服务器
   sections:                                                       
     - label: 从这里开始                                           # 一级目录：从这里开始
       sections:
         - href: ./releasenotes/releasenotes/_toc.yaml            # 手册：《发行说明》
         - href: ./quickstart/quickstart/_toc.yaml                # 手册：《快速入门》
     - label: 安装升级                                             # 一级目录：安装升级
       sections:
         - href: ./installation_upgrade/installation/_toc.yaml    # 手册：《安装指南》

修改文档 ​

文档修改分为以下三种情况：

• 仅内容修改：在现有手册章节中修改文档内容，例如，在《安装指南》的“安装方式介绍”章节中，添加一种新的安装方式。找到文档的存放位置，并对其内容进行相应调整，仅内容修改无需改动目录结构文件（_toc.yaml）。

• 新增、删除章节：找到手册的存放位置，新增或删除章节对应的内容文件，并修改手册的目录结构文件_toc.yaml。

  以在《升级指南》中增加“常用升级软件”章节为例，首先在《升级指南》的存放目录下，新增文档内容文件software.md，并在《升级指南》的 _toc.yaml 下，增加对software.md的引用：

  yaml

  label: 升级指南                                               # 手册名：《升级指南》
  isManual: true                                               # ismanual：识此文件是手册的目录结构文件，与场景的目录结构文件作区分
  description: 升级 openEuler 操作系统                          # 手册说明 
  sections:
    - label: 升降级指导                                         # 章节名：升降级指导
      href: ./openEuler_22.03_LTS_upgrade_and_downgrade.md     # 文档内容文件地址 
    - label: 常用升级软件                                       # 新增章节名：常用升级软件
      href: ./software.md                                      # 新增章节的内容文件地址

• 手册在文档中心呈现位置修改：找到所属场景的_toc.yaml并修改。

  例如，在服务器场景下，若开发者希望将《升级指南》调整至《安装指南》前面显示，需找到服务器场景的 _toc.yaml 文件并加以修改：

  yaml

  label: 服务器                                                      # 场景名：服务器
  sections:                                                       
    - label: 从这里开始                                              # 一级目录：从这里开始
      sections:
        - href: ./releasenotes/releasenotes/_toc.yaml               # 手册：《发行说明》
        - href: ./quickstart/quickstart/_toc.yaml                   # 手册：《快速入门》
    - label: '安装升级'                                              # 一级目录：安装升级
      sections:
        - href: ./installation_upgrade/upgrade/_toc.yaml'           # 《升级指南》放在《安装指南》上面
        - href: ./installation_upgrade/installation/_toc.yaml'      # 手册：《安装指南》
        - href: ./installation_upgrade/upgrade/_toc.yaml'
    - label: '系统管理'
      sections:
        - href: './administration/administrator/_toc.yaml'
        - href: './administration/sysmaster/_toc.yaml'
        - href: './administration/compa_command/_toc.yaml'

删除文档 ​

删除文档章节旨在指导开发者删除一本完整的手册。若要在现有手册中删除内容，比如在《管理员指南》中删除“管理进程”章节，则参考修改文档。

以在虚拟化场景下删除《虚拟化用户指南》为例，可参考以下操作步骤：

1. 首先，确定想要删除手册的存放位置，将其删除。

2. 在虚拟化场景的 _toc.yaml 文件中，删除对《OpenStack 用户手册》的引用。

   yaml

   label: 虚拟化                                                          # 场景：虚拟化
   sections:
     - label: 虚拟化平台                                                  # 一级目录：虚拟化平台
       sections:
         - href: ./virtualization_platform/virtualization/_toc.yaml      # 删除对《OpenStack 用户手册》目录结构文件的引用
         - href: ./virtualization_platform/stratovirt/_toc.yaml

文档暂不在文档中心发布 ​

如果开发者所创作的文档内容，暂时不适合推广或尚不成熟，目前无需发布在文档中心，可在文档仓的 archive 目录中进行增删改。等到需要发布时，再将其移至合适的目录，注意这类文档同样需要遵循写作规范。

注意：提交至 archive 目录的文档，按计划未来会发布到文档中心，若长时间无人维护，将会被清理。