文档组织架构
介绍
本文介绍 openEuler 文档的生产发布流程与文档仓的组织架构,同时提供每本手册在文档仓中的具体存放位置。
openEuler 文档的生产发布机制如上图所示。
- 文档中心将社区文档按业务场景和工具模块进行划分:
- 业务场景:服务器、虚拟化、云原生、边缘计算、嵌入式、DevStation。
- 工具:社区工具、DevOps、AI、图形桌面使用、云原生工具、系统运维、安全。
- 发布机制:
- 每个场景及工具模块均有对应目录配置文件(_toc.yaml)。这些配置文件均存于 openEuler/docs 仓,由 DOC SIG 集中管理。
- 各文档的责任 SIG 需将文档目录配置文件引用,添加到所属场景或工具模块的目录配置文件中,使文档可在对应模块下呈现。
- 文档生产:
- openEuler的文档生产在 openEuler/docs 仓以及各 SIG 组的文档/源码仓中进行。
- 基础特性文档,如发行说明、快速入门、安装、升级、管理员指南、配置与逻辑卷、配置网络、故障处理等,均存在 openEuler/docs 仓,由 DOC SIG 生产并维护。
- 增量特性文档,如 A-Tune 用户指南、x2openEuler 特性指南、oeAware 用户指南等,责任主体为特性所属的 SIG 组,分别存放在各 SIG 组的文档/源码仓内。
- 各 SIG 在文档/源码仓中维护的文件包括:内容文件和目录配置文件(_toc.yaml)。其中,内容文件用来存放文档实际内容,目录配置文件用来维护文档章节呈现结构。
在仓库中根目录 /docs 下设有 /zh 和 /en 两个子目录,分别用以存放发布至官网的中文文档与英文文档,文档目录结构严格参照官网呈现的目录层级规划设置。此外,文档仓可设 /archive 目录,用来存放暂不适合推广,或尚不成熟的文档。待文档完善且满足发布需求时,再将其移至 /docs 目录,以便在官网展示。
├─docs <!-- 在文档中心发布的文档 -->
│ ├─en <!-- 英文文档 -->
│ └─zh <!-- 中文文档 -->
仓库目录结构说明
openeuler/docs 仓库目录结构说明
场景
文档中心有五个业务场景,服务器、虚拟化、云原生、边缘计算、嵌入式和 DevStation,分别对应 openeuler/docs 仓内 docs/zh 目录下的 server、virtualization、cloud、edge_computing、embedded 和 devstation 子目录,工具模块对应 tools 子目录。
文档仓场景相关目录结构示例如下:
├─openeuler/docs 仓
├─docs
│ ├─en
│ └─zh
│ ├─server <!-- 场景:服务器 -->
│ ├─virtualization <!-- 场景:虚拟化 -->
│ ├─cloud <!-- 场景:云原生 -->
│ ├─edge_computing <!-- 场景:边缘计算 -->
│ ├─embedded <!-- 场景:嵌入式 -->
│ ├─devstation <!-- 场景:DevStation -->
│ └─tools <!-- 场景:工具 -->
工具模块下的子模块包括社区工具、DevOps、AI、图形桌面使用、云原生工具、系统运维和安全,分别对应 tools 目录下的 community_tools、devops、ai、desktop、cloud、maintenance 和 security 子目录。
文档仓工具相关目录结构示例如下:
├─docs
│ ├─en
│ └─zh
│ ├─server <!-- 场景:服务器 -->
│ ├─virtualization <!-- 场景:虚拟化 -->
│ ├─cloud <!-- 场景:云原生 -->
│ ├─edge_computing <!-- 场景:边缘计算 -->
│ ├─embedded <!-- 场景:嵌入式 -->
│ ├─devstation <!-- 场景:DevStation -->
│ └─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 <!-- 场景:嵌入式 -->
│ ├─devstation <!-- 场景:DevStation -->
│ └─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 <!-- 场景:嵌入式 -->
│ ├─devstation <!-- 场景:DevStation -->
│ └─tools <!-- 场景:工具 -->
手册
目录下存放手册。以服务器场景中的系统运维目录为例,其中包含四本基础特性文档,每本文档分别对应文档仓的一个文件夹。
文档仓服务器下系统运维的目录结构示例如下:
├─docs
│ ├─en
│ └─zh
│ ├─server <!-- 场景:服务器 -->
│ │ ├─releasenotes <!-- 一级目录:发行说明 -->
│ │ ├─quickstart <!-- 一级目录:快速入门 -->
│ │ ├─installation_upgrade <!-- 一级目录:安装升级 -->
│ │ ├─administration <!-- 一级目录:系统管理 -->
│ │ ├─maintenance <!-- 一级目录:系统运维 -->
│ │ │ ├─common_skills <!-- 手册:《常用技能》 -->
│ │ │ ├─common_tools <!-- 手册:《常用定位定界工具》 -->
│ │ │ ├─kernel_live_upgrade <!-- 手册:《内核热升级指南》 -->
│ │ │ └─trouble_shooting <!-- 手册:《故障应急处理》 -->
| | ├─security <!-- 一级目录:安全 -->
│ │ ├─memory_storage <!-- 一级目录:内存与存储 -->
│ │ ├─network <!-- 一级目录:网络 -->
│ │ ├─performance <!-- 一级目录:性能调优 -->
│ │ ├─development <!-- 一级目录:应用开发 -->
│ │ ├─high_availability <!-- 一级目录:ha高可用 -->
│ │ ├─diversified_computing <!-- 一级目录:多样性算力 -->
│ │ └─_toc.yaml
│ ├─virtualization <!-- 场景:虚拟化 -->
│ ├─cloud <!-- 场景:云原生 -->
│ ├─edge_computing <!-- 场景:边缘计算 -->
│ ├─embedded <!-- 场景:嵌入式 -->
│ ├─devstation <!-- 场景:DevStation -->
│ └─tools <!-- 场景:工具 -->
每本手册包含一个或多个文档内容文件(.md
文件)对应一个或多个章节,及一个目录配置文件(_toc.yaml
文件)。例如,《内核热升级指南》手册中包括三个章节,包括安装与部署、使用方法、常用问题与解决办法。
├─docs
│ ├─en
│ └─zh
│ ├─server <!-- 场景:服务器 -->
│ │ ├─quickstart <!-- 一级目录:快速入门 -->
│ │ ├─releasenotes <!-- 一级目录:发行说明 -->
│ │ ├─installation_upgrade <!-- 一级目录:安装升级 -->
│ │ ├─administration <!-- 一级目录:系统管理 -->
│ │ ├─maintenance <!-- 一级目录:系统运维 -->
│ │ │ ├─common_skills <!-- 手册:《常用技能》 -->
│ │ │ ├─common_tools <!-- 手册:《常用定位定界工具》 -->
│ │ │ ├─kernel_live_upgrade <!-- 手册:《内核热升级指南》 -->
│ | │ │ ├─installation-and-deployment.md <!-- 章节:安装与部署 -->
│ | │ │ ├─how-to-run.md <!-- 章节:使用方法 -->
│ | │ │ ├─common-problems-and-solutions.md <!-- 章节:常用问题与解决办法 -->
│ | │ │ └─_toc.yaml
│ │ │ └─trouble_shooting <!-- 手册:《故障应急处理》 -->
| | ├─security <!-- 一级目录:安全 -->
│ │ ├─memory_storage <!-- 一级目录:内存与存储 -->
│ │ ├─network <!-- 一级目录:网络 -->
│ │ ├─performance <!-- 一级目录:性能调优 -->
│ │ ├─development <!-- 一级目录:应用开发 -->
│ │ ├─high_availability <!-- 一级目录:ha高可用 -->
│ │ ├─diversified_computing <!-- 一级目录:多样性算力 -->
│ │ └─_toc.yaml
│ ├─virtualization <!-- 场景:虚拟化 -->
│ ├─cloud <!-- 场景:云原生 -->
│ ├─edge_computing <!-- 场景:边缘计算 -->
│ ├─embedded <!-- 场景:嵌入式 -->
│ ├─devstation <!-- 场景:DevStation -->
│ └─tools <!-- 场景:工具 -->
SIG 组代码仓库目录结构说明
手册
SIG 组文档/源码仓库仅存放特性手册,《oeAware用户指南》的目录结构示例如下:
├─openeuler/oeAware-manager 仓
├─docs
| ├─en
| └─zh
| └─2403_lts_sp2 <!-- 版本:openEuler 24.03 LTS SP2 -->
| ├─oeawrae_user_guide.md <!-- 章节:使用oeAware -->
| └─_toc.yaml
SIG 组文档目录结构规范
约束
- 分版本写文档,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://gitee.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/
目录配置文件格式
各个场景、每本手册均配置一个_toc.yaml
文件,以维护目录结构。所有场景的_toc.yaml
文件均存在 openeuler/docs 仓库,手册的_toc.yaml
与手册源文件放在一起。 下面以服务器场景为例展示_toc.yaml
的存放位置,其他场景的存放逻辑类似。
├─openeuler/docs 仓
├─docs
│ └─zh
│ ├─server <!-- 场景:服务器 -->
│ │ ├─installation_upgrade <!-- 一级目录:安装升级 -->
│ │ | ├─installation <!-- 手册:《安装指南》 -->
│ │ | | └─_toc.yaml
│ │ | ├─upgrade <!-- 手册:《升级指南》 -->
│ │ | | └─_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
- 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:
upstream: https://gitee.com/openeuler/aops-zeus/blob/master/docs/zh/24.03_lts_sp2/_toc.yaml
path: ./aops
- href: ./maintenance/gala/_toc.yaml
- href: ./maintenance/sysmonitor/_toc.yaml
- href: ./maintenance/kernel_live_upgrade/_toc.yaml
- href:
upstream: https://gitee.com/openeuler/syscare/blob/openEuler-24.03-LTS-SP2/docs/zh/_toc.yaml
path: ./syscare
- href: ./maintenance/common_skills/_toc.yaml
- href: ./maintenance/common_tools/_toc.yaml
- href: ./maintenance/troubleshooting/_toc.yaml
- label: 安全
sections:
- href: ./security/secharden/_toc.yaml
- href: ./security/trusted_computing/_toc.yaml
- href:
upstream: https://gitee.com/openeuler/secGear/blob/master/docs/zh/2403_LTS_SP2/_toc.yaml
path: ./secgear
- href:
upstream: https://gitee.com/openeuler/cve-ease/blob/master/docs/zh/24.03_lts_sp2/_toc.yaml
path: ./cve_ease
- href: ./security/cert_signature/_toc.yaml
- href: ./security/shangmi/_toc.yaml
- href:
upstream: https://gitee.com/openeuler/secDetector/blob/master/docs/zh/2403_LTS_SP2/_toc.yaml
path: ./secdetector
- 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: ./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
path: ./performance/tuning_framework/oeaware
- label: CPU调优
sections:
- href: ./performance/cpu_optimization/sysboost/_toc.yaml
- href: ./performance/cpu_optimization/kae/_toc.yaml
- label: 系统调优
sections:
- href:
upstream: https://gitee.com/openeuler/A-Tune/blob/master/docs/zh/24.03_LTS_SP2/_toc.yaml
path: ./performance/system_optimization/atune
- label: 应用开发
sections:
- href: ./development/application_dev/_toc.yaml
- href:
upstream: https://gitee.com/openeuler/compiler-docs/blob/openEuler-24.03-LTS-SP2/docs/zh/gcc/_toc.yaml
path: ./compiler/gcc
- href:
upstream: https://gitee.com/openeuler/compiler-docs/blob/openEuler-24.03-LTS-SP2/docs/zh/llvm/_toc.yaml
path: ./compiler/llvm
- href:
upstream: https://gitee.com/openeuler/compiler-docs/blob/openEuler-24.03-LTS-SP2/docs/zh/bisheng_autotuner/_toc.yaml
path: ./compiler/bisheng_autotuner
- href: ./development/ai4c/_toc.yaml
- href: ./development/fangtian/_toc.yaml
- href: ./development/annc/_toc.yaml
- href: ./development/unt/_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:手册的目录配置文件引用。
- upstream(仅增量特性文档):增量特性手册的目录配置文件引用。
- path(仅增量特性文档):手册的url访问路径(可选,默认值是“./仓库名”)。
- href:手册的目录配置文件引用。
文档存放地址
openEuler 文档存储于 openEuler/docs 仓和各 SIG 的文档/源码仓。以下为您提供每本手册在文档仓中的具体存放地址。
服务器
虚拟化
场景 | 类别 | 手册 | 存放地址 |
---|---|---|---|
虚拟化 | 虚拟化平台 | 虚拟化用户指南 | openeuler/Virt-docs/docs/zh/virtualization_platform/virtualization |
StratoVirt用户指南 | openeuler/Virt-docs/docs/zh/virtualization_platform/stratovirt | ||
OpenStack用户手册 | openstack-docs/docs/zh |
云原生
边缘计算
场景 | 类别 | 手册 | 存放地址 |
---|---|---|---|
边缘计算 | / | KubeEdge部署指南 | openeuler/docs/docs/zh/edge_computing/kube_edge |
K3s部署指南 | openeuler/docs/docs/zh/edge_computing/k3s |
嵌入式
场景 | 类别 | 手册 | 存放地址 |
---|---|---|---|
嵌入式 | / | openEuler Embedded用户指南 | yocto-meta-openeuler/docs |
UniProton用户指南 | openeuler/UniProton/docs/zh |
工具
工具模块 | 类别 | 手册 | 存放地址 |
---|---|---|---|
社区工具 | 镜像构建 | isocut使用指南 | docs/zh/tools/community_tools/isocut |
imageTailor使用指南 | docs/zh/tools/community_tools/image_tailor | ||
编译 | GCC用户指南 | openeuler/compiler-docs/docs/zh/gcc | |
性能优化 | A-Tune用户指南 | openeuler/A-Tune/docs/zh/24.03_LTS_SP2 | |
oeAware用户指南 | openeuler/oeAware-manager/docs/zh/2403_lts_sp2 | ||
迁移 | Migration-tools用户指南 | docs/zh/tools/community_tools/migration_tools | |
虚拟化 | EulerLauncher用户指南 | docs/zh/tools/community_tools/virtualization/euler_launcher | |
epkg软件包 | epkg包管理器使用指南 | docs/zh/tools/community_tools/epkg_use | |
社区服务 | 源码管理 | patch-tracking | docs/zh/tools/devops/patch_tracking |
包管理 | pkgship | docs/zh/tools/devops/pkgship | |
图形桌面使用 | / | Gnome用户指南 | docs/zh/tools/desktop/gnome |
UKUI用户指南 | docs/zh/tools/desktop/ukui | ||
DDE用户指南 | docs/zh/tools/desktop/dde | ||
Kiran用户指南 | docs/zh/tools/desktop/kiran | ||
云原生工具 | / | CTinspector用户指南 | docs/zh/tools/cloud/ctinspector |
CPDS用户指南 | docs/zh/tools/cloud/cpds | ||
PilotGo用户指南 | docs/zh/tools/cloud/pilotgo | ||
系统运维 | 热补丁制作 | SysCare用户指南 | openeuler/syscare/docs/zh |
系统监控 | sysmonitor用户指南 | docs/zh/server/maintenance/sysmonitor | |
安全 | / | secGear开发指南 | openeuler/secGear/docs/zh/2403_LTS_SP2 |