概述
介绍
本文介绍 openEuler 文档的生产发布流程与文档仓的组织架构,同时提供每本手册在文档仓中的具体存放位置。
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 目录,以便在官网展示。
├─docs <!-- 在文档中心发布的文档 -->
│ ├─en <!-- 英文文档 -->
│ └─zh <!-- 中文文档 -->
├─archive <!-- 不在文档中心发布的文档 -->
文档仓目录结构说明
场景
文档中心有五个业务场景,服务器、虚拟化、云原生、边缘计算和嵌入式,分别对应 docs 仓内 docs/zh 目录下的 server、virtualization、cloud、edge_computing 和 embedded 子目录,工具模块对应 tools 子目录。
文档仓场景相关目录结构示例如下:
├─Archive
├─docs
│ ├─en
│ └─zh
│ ├─server <!-- 场景:服务器 -->
│ ├─virtualization <!-- 场景:虚拟化 -->
│ ├─cloud <!-- 场景:云原生 -->
│ ├─edge_computing <!-- 场景:边缘计算 -->
│ ├─embedded <!-- 场景:嵌入式 -->
│ └─tools <!-- 场景:工具 -->
工具模块下的子模块包括社区工具、DevOps、AI、图形桌面使用、云原生工具、系统运维和安全,分别对应 tools 目录下的 community_tools、devops、ai、desktop、cloud、maintenance 和 security 子目录。
文档仓工具相关目录结构示例如下:
├─docs
│ ├─en
│ └─zh
│ ├─server <!-- 场景:服务器 -->
│ ├─virtualization <!-- 场景:虚拟化 -->
│ ├─cloud <!-- 场景:云原生 -->
│ ├─edge_computing <!-- 场景:边缘计算 -->
│ ├─embedded <!-- 场景:嵌入式 -->
│ └─tools <!-- 场景:工具 -->
│ ├─community_tools <!-- 工具模块:社区工具 -->
│ ├─devops <!-- 工具模块:devops(社区服务) -->
│ ├─ai <!-- 工具模块:ai -->
│ ├─desktop <!-- 工具模块:图形桌面使用 -->
│ ├─cloud <!-- 工具模块:云原生工具 -->
│ ├─maintenance <!-- 工具模块:系统运维 -->
│ └─security <!-- 工具模块:安全 -->
目录
各业务场景下均有具体的目录划分。以服务器场景为例,其进一步细分为发行说明、快速入门、安装升级、系统管理、系统运维等一级目录。
文档仓服务器场景目录结构示例如下:
├─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调优、系统调优、调优框架。
文档仓服务器下性能调优的目录结构示例如下:
├─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 <!-- 场景:工具 -->
手册
目录下存放手册。以服务器场景中的系统运维目录为例,其中包含八本手册,每本手册分别对应文档仓的一个文件夹。
文档仓服务器下系统运维的目录结构示例如下:
├─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
文件)。例如,《内核热升级指南》手册中包括三个章节,包括安装与部署、使用方法、常用问题与解决办法。
├─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
的存放位置,其他场景的存放逻辑类似。
├─docs
│ └─zh
│ ├─virtualization <!-- 场景:虚拟化 -->
│ │ ├─vitualization_platform <!-- 一级目录:虚拟化平台 -->
│ │ | ├─stratovirt <!-- 手册:《StratoVirt用户指南》 -->
│ │ | | └─_toc.yaml
│ │ | ├─virtualization <!-- 手册:《虚拟化用户指南》 -->
│ │ | | └─_toc.yaml
│ │ └─_toc.yaml
手册的目录结构文件
每本手册都需要维护一个目录结构文件_toc.yaml
来维护该本手册中各章节间的逻辑关系。
《内核热升级指南》手册的_toc.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
文件示例如下:
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/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 |