文档开发指南

概述

介绍

本文介绍 openEuler 文档的生产发布流程与文档仓的组织架构,同时提供每本手册在文档仓中的具体存放位置。

image

openEuler 文档的生产发布机制如上图所示。

  • 文档中心将社区文档按业务场景和工具模块进行划分:
    • 业务场景:服务器、虚拟化、云原生、边缘计算、嵌入式。
    • 工具:社区工具、DevOps、AI、图形桌面使用、云原生工具、系统运维、安全。
  • 发布机制:
    • 每个场景及工具模块均有对应目录结构文件(_toc.yaml)。这些配置文件均存于 openEuler/docs 仓,由 DOC SIG 集中管理。
    • 各文档的责任 SIG 需将文档目录结构文件引用,添加到所属场景或工具模块的目录结构文件中,使文档可在对应模块下呈现。
  • 文档生产:
    • openEuler的文档生产在 openEuler/docs 仓以及各 SIG 组的 docs 仓中进行。
    • 基础特性文档,如发行说明、快速入门、安装、升级、管理员指南、配置与逻辑卷、配置网络、故障处理等,均存在 openEuler/docs 仓,由 DOC SIG 生产并维护。
    • 增量特性文档,如 A-Tune 用户指南、x2openEuler 特性指南、oeAware 用户指南等,责任主体为特性所属的 SIG 组,分别存放在各 SIG 组的 docs 仓内。
    • 各 SIG 在文档仓中维护的文件包括:文档内容文件和目录结构文件(_toc.yaml)。其中,文档内容文件用来存放文档实际内容,文档目录结构文件用来维护文档章节呈现结构。

在文档仓中,docs 目录下的内容会展示于官网,其下设有 zh 和 en 两个子目录,分别用以存放中文文档与英文文档,文档目录结构严格参照官网呈现的目录层级规划设置。此外,文档仓还设有 archive 目录,用来存放暂不适合推广,或尚不成熟的文档。待文档完善且满足发布需求时,再将其移至 docs 目录,以便在官网展示。

text
├─docs     <!-- 在文档中心发布的文档 -->
│  ├─en    <!-- 英文文档 -->
│  └─zh    <!-- 中文文档 -->
├─archive  <!-- 不在文档中心发布的文档 -->

文档仓目录结构说明

场景

文档中心有五个业务场景,服务器、虚拟化、云原生、边缘计算和嵌入式,分别对应 docs 仓内 docs/zh 目录下的 server、virtualization、cloud、edge_computing 和 embedded 子目录,工具模块对应 tools 子目录。

文档仓场景相关目录结构示例如下:

text
├─Archive
├─docs
│  ├─en
│  └─zh
│     ├─server          <!-- 场景:服务器 -->
│     ├─virtualization  <!-- 场景:虚拟化 -->
│     ├─cloud           <!-- 场景:云原生 -->
│     ├─edge_computing  <!-- 场景:边缘计算 -->
│     ├─embedded        <!-- 场景:嵌入式 -->
│     └─tools           <!-- 场景:工具 -->

工具模块下的子模块包括社区工具、DevOps、AI、图形桌面使用、云原生工具、系统运维和安全,分别对应 tools 目录下的 community_tools、devops、ai、desktop、cloud、maintenance 和 security 子目录。

文档仓工具相关目录结构示例如下:

text
├─docs
│  ├─en
│  └─zh
│     ├─server              <!-- 场景:服务器 -->
│     ├─virtualization      <!-- 场景:虚拟化 -->
│     ├─cloud               <!-- 场景:云原生 -->
│     ├─edge_computing      <!-- 场景:边缘计算 -->
│     ├─embedded            <!-- 场景:嵌入式 -->
│     └─tools               <!-- 场景:工具 -->
│        ├─community_tools  <!-- 工具模块:社区工具 -->
│        ├─devops           <!-- 工具模块:devops(社区服务) -->
│        ├─ai               <!-- 工具模块:ai -->
│        ├─desktop          <!-- 工具模块:图形桌面使用 -->
│        ├─cloud            <!-- 工具模块:云原生工具 -->
│        ├─maintenance      <!-- 工具模块:系统运维 -->
│        └─security         <!-- 工具模块:安全 -->

目录

各业务场景下均有具体的目录划分。以服务器场景为例,其进一步细分为发行说明、快速入门、安装升级、系统管理、系统运维等一级目录。

文档仓服务器场景目录结构示例如下:

text
├─docs
│  ├─en
│  └─zh
│      ├─server                     <!-- 场景:服务器 -->
│      │  ├─releasenotes            <!-- 一级目录:发行说明 -->
│      │  ├─quickstart              <!-- 一级目录:快速入门 -->
│      │  ├─installation_upgrade    <!-- 一级目录:安装升级 -->
│      │  ├─administration          <!-- 一级目录:系统管理 -->
│      │  ├─maintenance             <!-- 一级目录:系统运维 -->
|      |  ├─security                <!-- 一级目录:安全 -->
│      │  ├─memory_storage          <!-- 一级目录:内存与存储 -->
│      │  ├─network                 <!-- 一级目录:网络 -->
│      │  ├─performance             <!-- 一级目录:性能调优 -->
│      │  ├─development             <!-- 一级目录:应用开发 -->
│      │  ├─high_availability       <!-- 一级目录:ha高可用 -->
│      │  ├─diversified_computing   <!-- 一级目录:多样性算力 -->
│      │  └─_toc.yaml       
│      ├─virtualization             <!-- 场景:虚拟化 -->
│      ├─cloud                      <!-- 场景:云原生 -->
│      ├─edgecomputing              <!-- 场景:边缘计算 -->
│      ├─embedded                   <!-- 场景:嵌入式 -->         
│      └─tools                      <!-- 场景:工具 -->

部分一级目录会进一步细分出二级目录,以服务器场景中的性能调优目录为例,其下进一步划分出二级目录,分别为概述、CPU调优、系统调优、调优框架。

文档仓服务器下性能调优的目录结构示例如下:

text
├─docs
│  ├─en
│  └─zh
│      ├─server                      <!-- 场景:服务器 -->
│      │  ├─releasenotes             <!-- 一级目录:发行说明 -->
│      │  ├─quickstart               <!-- 一级目录:快速入门 -->
│      │  ├─installation_upgrade     <!-- 一级目录:安装升级 -->
│      │  ├─administration           <!-- 一级目录:系统管理 -->
│      │  ├─maintenance              <!-- 一级目录:系统运维 -->
|      |  ├─security                 <!-- 一级目录:安全 -->
│      │  ├─memory_storage           <!-- 一级目录:内存与存储 -->
│      │  ├─network                  <!-- 一级目录:网络 -->
│      │  ├─performance              <!-- 一级目录:性能调优 -->
│      │  │  ├─overall               <!-- 二级目录:概述 -->
│      │  │  │  └─system_resource
│      │  │  ├─cpu_optimization      <!-- 二级目录:cpu调优 -->
│      │  │  │  ├─kae
│      │  │  │  └─sysboost
│      │  │  ├─system_optimization   <!-- 二级目录:系统调优 -->
│      │  │  │  └─atune
│      │  │  └─tuning_framework      <!-- 二级目录:调优框架 -->
│      │  │      └─oeaware
│      │  ├─development              <!-- 一级目录:应用开发 -->
│      │  ├─high_availability        <!-- 一级目录:ha高可用 -->
│      │  ├─diversified_computing    <!-- 一级目录:多样性算力 -->
│      │  └─_toc.yaml
│      ├─virtualization              <!-- 场景:虚拟化 -->
│      ├─cloud                       <!-- 场景:云原生 -->
│      ├─edge_computing              <!-- 场景:边缘计算 -->
│      ├─embedded                    <!-- 场景:嵌入式 -->
│      └─tools                       <!-- 场景:工具 -->

手册

目录下存放手册。以服务器场景中的系统运维目录为例,其中包含八本手册,每本手册分别对应文档仓的一个文件夹。

文档仓服务器下系统运维的目录结构示例如下:

text
├─docs
│   ├─en
│   └─zh
│      ├─server                     <!-- 场景:服务器 -->
│      │  ├─releasenotes            <!-- 一级目录:发行说明 -->
│      │  ├─quickstart              <!-- 一级目录:快速入门 -->
│      │  ├─installation_upgrade    <!-- 一级目录:安装升级 -->
│      │  ├─administration          <!-- 一级目录:系统管理 -->
│      │  ├─maintenance             <!-- 一级目录:系统运维 -->
│      │  │  ├─aops                 <!-- 手册:《a-ops 用户指南》 -->
│      │  │  ├─common_skills        <!-- 手册:《常用技能》 -->
│      │  │  ├─common_tools         <!-- 手册:《常用定位定界工具》 -->
│      │  │  ├─gala                 <!-- 手册:《gala 用户指南》 -->
│      │  │  ├─kernel_live_upgrade  <!-- 手册:《内核热升级指南》 -->
│      │  │  ├─syscare              <!-- 手册:《syscare 用户指南》 -->
│      │  │  ├─sysmonitor           <!-- 手册:《sysmonitor 用户指南》 -->
│      │  │  └─trouble_shooting     <!-- 手册:《故障应急处理》 -->
|      |  ├─security                <!-- 一级目录:安全 -->
│      │  ├─memory_storage          <!-- 一级目录:内存与存储 -->
│      │  ├─network                 <!-- 一级目录:网络 -->
│      │  ├─performance             <!-- 一级目录:性能调优 -->
│      │  ├─development             <!-- 一级目录:应用开发 -->
│      │  ├─high_availability       <!-- 一级目录:ha高可用 -->
│      │  ├─diversified_computing   <!-- 一级目录:多样性算力 -->
│      │  └─_toc.yaml
│      ├─virtualization             <!-- 场景:虚拟化 -->
│      ├─cloud                      <!-- 场景:云原生 -->
│      ├─edge_computing             <!-- 场景:边缘计算 -->
│      ├─embedded                   <!-- 场景:嵌入式 -->
│      └─tools                      <!-- 场景:工具 -->

每本手册包含一个或多个文档内容文件(.md文件)对应一个或多个章节,及一个目录结构文件(_toc.yaml文件)。例如,《内核热升级指南》手册中包括三个章节,包括安装与部署、使用方法、常用问题与解决办法。

text
├─docs
│  ├─en
│  └─zh
│      ├─server                                        <!-- 场景:服务器 -->
│      │  ├─quickstart                                 <!-- 类别:快速入门 -->
│      │  ├─releasenotes                               <!-- 类别:发行说明 -->
│      │  ├─installation_upgrade                       <!-- 类别:安装升级 -->
│      │  ├─administration                             <!-- 类别:系统管理 -->
│      │  ├─maintenance                                <!-- 一级目录:系统运维 -->
│      │  │  ├─aops                                    <!-- 手册:《a-ops 用户指南》 -->
│      │  │  ├─common_skills                           <!-- 手册:《常用技能》 -->
│      │  │  ├─common_tools                            <!-- 手册:《常用定位定界工具》 -->
│      │  │  ├─gala                                    <!-- 手册:《gala 用户指南》 -->
│      │  │  ├─kernel_live_upgrade                     <!-- 手册:《内核热升级指南》 -->
│      |  │  │  ├─installation-and-deployment.md       <!-- 章节:安装与部署 -->
│      |  │  │  ├─how-to-run.md                        <!-- 章节:使用方法 -->
│      |  │  │  ├─common-problems-and-solutions.md     <!-- 章节:常用问题与解决办法 -->
│      |  │  │  └─_toc.yaml
|      |  ├─security                                   <!-- 一级目录:安全 -->
│      │  ├─memory_storage                             <!-- 一级目录:内存与存储 -->
│      │  ├─network                                    <!-- 一级目录:网络 -->
│      │  ├─performance                                <!-- 一级目录:性能调优 -->
│      │  ├─development                                <!-- 一级目录:应用开发 -->
│      │  ├─high_availability                          <!-- 一级目录:ha高可用 -->
│      │  ├─diversified_computing                      <!-- 一级目录:多样性算力 -->
│      │  └─_toc.yaml
│      ├─cloud                                         <!-- 场景:云原生 -->
│      ├─edge_computing                                <!-- 场景:边缘计算 -->
│      ├─embedded                                      <!-- 场景:嵌入式 -->
│      ├─tools                                         <!-- 场景:工具 -->
│      └─virtualization                                <!-- 场景:虚拟化 -->

目录结构文件格式

各个场景、每本手册均配置一个_toc.yaml文件,以维护目录结构。下面以虚拟化场景为例展示_toc.yaml的存放位置,其他场景的存放逻辑类似。

text
├─docs
│  └─zh
│     ├─virtualization                                 <!-- 场景:虚拟化 -->
│     │   ├─vitualization_platform                     <!-- 一级目录:虚拟化平台 -->
│     │   |  ├─stratovirt                              <!-- 手册:《StratoVirt用户指南》 -->
│     │   |  |   └─_toc.yaml
│     │   |  ├─virtualization                          <!-- 手册:《虚拟化用户指南》 -->
│     │   |  |   └─_toc.yaml
│     │   └─_toc.yaml

手册的目录结构文件

每本手册都需要维护一个目录结构文件_toc.yaml来维护该本手册中各章节间的逻辑关系。

《内核热升级指南》手册的_toc.yaml文件示例如下:

yaml
label: 内核热升级指南
isManual: true
description: 使用用户态自动化工具快速重启内核和程序热迁移实现内核热替换特性
sections:
  - label: 安装与部署
    href: ./installation-and-deployment.md
  - label: 使用方法
    href: ./how-to-run.md
  - label: 常见问题与解决方法
    href: ./common-problems-and-solutions.md
  • label:手册名称。
  • isManual:标识手册的目录结构文件,与场景的目录结构文件作区分。
  • description:手册的简介说明。
  • sections:
    • label:章节名称。
    • href:文档内容文件地址(建议使用相对路径)。

场景的目录结构文件

各业务场景下也要维护_toc.yaml文件,其中引用手册的_toc.yaml文件。以服务器场景为例,其_toc.yaml文件示例如下:

yaml
label: 服务器
sections:
  - label: 发行说明
    sections:
      - href: ./releasenotes/releasenotes/_toc.yaml
  - label: 快速入门
    sections:
      - href: ./quickstart/quickstart/_toc.yaml
  - label: 安装升级
    sections:
      - 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
  - label: 系统运维
    sections:
      - href: ./maintenance/aops/_toc.yaml
      - href: ./maintenance/gala/_toc.yaml
      - href: ./maintenance/sysmonitor/_toc.yaml
      - href: ./maintenance/kernel_live_upgrade/_toc.yaml
      - href: ./maintenance/syscare/_toc.yaml
      - href: ./maintenance/common_skills/_toc.yaml
      - href: ./maintenance/common_tools/_toc.yaml
      - href: ./maintenance/trouble_shooting/_toc.yaml
  - label: 安全
    sections:
      - href: ./security/secharden/_toc.yaml
      - href: ./security/trusted_computing/_toc.yaml
      - href: ./security/secgear/_toc.yaml
      - href: ./security/cve-ease/_toc.yaml
      - href: ./security/cert_signature/_toc.yaml
      - href: ./security/sbom/_toc.yaml
      - href: ./security/shangmi/_toc.yaml
  - label: 内存与存储
    sections:
      - href: ./memory_storage/lvm/_toc.yaml
      - href: ./memory_storage/etmem/_toc.yaml
      - href: ./memory_storage/gmem/_toc.yaml
      - href: ./memory_storage/hsak/_toc.yaml
  - label: 网络
    sections:
      - href: ./network/network_config/_toc.yaml
      - href: ./network/gazelle/_toc.yaml
  - label: 性能调优
    sections:
      - label: 概述
        sections:
          - href: ./system_resource/_toc.yaml
      - label: 调优框架
        sections:
          - href: ./oeaware/_toc.yaml
      - label: cpu调优
        sections:
          - href: ./sysboost/_toc.yaml
          - href: ./kae/_toc.yaml
      - label: 系统调优
        sections:
          - href: ./atune/_toc.yaml
  - label: 应用开发
    sections:
      - href: ./development/applicationdev/_toc.yaml
      - href: ./development/gcc/_toc.yaml
  - label: ha高可用
    sections:
      - href: ./high_availability/ha/_toc.yaml
  - label: 多样性算力
    sections:
      - href: ./diversified_computing/dpu_offload/_toc.yaml
      - href: ./diversified_computing/dpu_os/_toc.yaml
  • label:场景名称。
  • description:场景的简介说明。
  • sections:
    • label: 一级目录名称。
    • sections:
      • href:手册的目录结构文件引用。

文档存放地址

openEuler 文档存储于 openEuler/docs 仓和各 SIG 的文档仓。以下为您提供每本手册在文档仓中的具体存放地址。

服务器

场景类别手册存放地址
服务器发行说明发行说明docs/zh/server/releasenotes/releasenotes
快速入门快速入门docs/zh/server/quickstart/quickstart
安装升级安装指南docs/zh/server/installation_upgrade/installation
升级指南docs/zh/server/installation_upgrade/upgrade
系统管理管理员指南docs/zh/server/administration/administrator
sysMaster用户指南docs/zh/server/administration/sysmaster
兼容性命令docs/zh/server/administration/compa_command
系统运维A-Ops用户指南docs/zh/server/maintenance/aops
gala用户指南docs/zh/server/maintenance/gala
sysmonitor用户指南docs/zh/server/maintenance/sysmonitor
内核热升级指南docs/zh/server/maintenance/kernel_live_upgrade
SysCare用户指南docs/zh/server/maintenance/syscare
常用技能docs/zh/server/maintenance/common_skills
常用定位定界工具docs/zh/server/maintenance/common_tools
故障应急处理docs/zh/server/maintenance/troubleshooting
安全安全加固指南docs/zh/server/security/secharden
可信计算docs/zh/server/security/trusted_computing
secGear开发指南docs/zh/server/security/secgear
CVE-ease设计指南docs/zh/server/security/cve-ease
证书签名docs/zh/server/security/cert_signature
SBOM用户指南docs/zh/server/security/sbom
国密docs/zh/server/security/shangmi
内存与存储配置和管理逻辑卷docs/zh/server/memory_storage/lvm
etmem用户指南docs/zh/server/memory_storage/etmem
GMEM用户指南docs/zh/server/memory_storage/gmem
HSAK开发指南docs/zh/server/memory_storage/hsak
网络配置网络docs/zh/server/network/network_config
Gazelle用户指南docs/zh/server/network/gazelle
性能调优系统资源与性能docs/zh/server/performance/overall/system_resource
oeAware用户指南docs/zh/server/performance/tuning_framework/oeaware
sysBoost用户指南docs/zh/server/performance/cpu_optimization/sysboost
使用KAE加速引擎docs/zh/server/performance/cpu_optimization/kae
A-Tune用户指南docs/zh/server/performance/system_optimization/atune
应用开发应用开发指南docs/zh/server/development/application_dev
GCC用户指南docs/zh/server/development/gcc
HA高可用HA用户指南docs/zh/server/high_availability/ha
多样性算力直连聚合用户指南docs/zh/server/diversified_computing/dpu_offload
DPU-OSdocs/zh/server/diversified_computing/dpu_os

虚拟化

场景类别手册存放地址
虚拟化虚拟化平台虚拟化用户指南docs/zh/virtualization/virtualization_platform/virtualization
StratoVirt用户指南docs/zh/virtualization/virtualization_platform/stratovirt
OpenStack用户手册openstack-docs/docs/zh

云原生

场景类别手册存放地址
云原生容器引擎iSula容器引擎docs/zh/cloud/container_engine/isula_container_engine
Docker容器docs/zh/cloud/container_engine/docker_engine
容器形态安全容器docs/zh/cloud/container_form/secure_container
系统容器docs/zh/cloud/container_form/system_container
容器运行时Kuasar多沙箱容器运行时docs/zh/cloud/container_runtime/kuasar
容器镜像构建工具容器镜像构建docs/zh/cloud/image_builder/isula-build
云原生操作系统容器OS升级用户指南docs/zh/cloud/kubeos/kubeos
云底座操作系统NestOS用户指南docs/zh/cloud/nestosS/nestos
混合部署云原生混合部署rubik用户指南docs/zh/cloud/hybrid_deployment/rubik
oncn-bwm用户指南docs/zh/cloud/hybrid_deployment/oncn-bwm
集群部署Kubernetes集群部署指南docs/zh/cloud/cluster_deployment/kubernetes
iSulad+k8s集群部署指南docs/zh/cloud/cluster_deployment/isulad+k8s
服务网格Kmesh用户指南docs/zh/cloud/kmesh/kmesh

边缘计算

场景类别手册存放地址
边缘计算 / KubeEdge部署指南docs/zh/edge_computing/kube_edge
K3s部署指南docs/zh/edge_computing/k3s

嵌入式

场景类别手册存放地址
嵌入式 / openEuler Embedded用户指南yocto-meta-openeuler/docs
UniProton用户指南docs/zh/embedded/uniproton

工具

工具模块类别手册存放地址
社区工具镜像构建isocut使用指南docs/zh/tools/community_tools/image_custom/isocut
imageTailor使用指南docs/zh/tools/community_tools/image_custom/image_tailor
编译GCC用户指南docs/zh/server/development/gcc
性能优化A-Tune用户指南docs/zh/server/performance/system_optimization/atune
oeAware用户指南docs/zh/server/performance/tuning_framework/oeaware
迁移Migration-tools用户指南docs/zh/tools/community_tools/migration/migration_tools
虚拟化EulerLauncher用户指南docs/zh/tools/community_tools/virtualization/euler_launcher
epkg软件包epkg包管理器使用指南docs/zh/tools/community_tools/epkg/epkg_use
autopkg用户指南docs/zh/tools/community_tools/epkg/autopkg
社区服务源码管理patch-trackingdocs/zh/tools/devops/code_manage/patch_tracking
包管理pkgshipdocs/zh/tools/devops/package_manage/pkgship
AI / openEuler Copilot Systemdocs/zh/tools/ai/openeuler_copilot_system
AI大模型服务镜像使用指南docs/zh/tools/ai/ai_large_model_service_images_userguide
AI容器镜像用户指南docs/zh/tools/ai/ai_container_image_userguide
图形桌面使用 / Gnome用户指南docs/zh/tools/desktop/gnome
UKUI用户指南docs/zh/tools/desktop/ukui
DDE用户指南docs/zh/tools/desktop/dde
Kiran用户指南docs/zh/tools/desktop/kiran
XFCE用户指南docs/zh/tools/desktop/xfce
云原生工具 / CTinspector用户指南docs/zh/tools/cloud/ctinspector
CPDS用户指南docs/zh/tools/cloud/cpds
PilotGo用户指南docs/zh/tools/cloud/pilotgo
系统运维热补丁制作SysCare用户指南docs/zh/server/maintenance/syscare
系统监控sysmonitor用户指南docs/zh/server/maintenance/sysmonitor
安全 / secGear开发指南docs/zh/server/security/secgear