diff --git a/docs/zh/Contribute/_menu.md b/docs/zh/Contribute/_menu.md index 82d53c7bfa0dc479a4247decba91114f2f7f61ef..d57839bbf4e2451330e51ba7fe6539f9ccfb2ef1 100644 --- a/docs/zh/Contribute/_menu.md +++ b/docs/zh/Contribute/_menu.md @@ -4,7 +4,7 @@ ismanual: 'Y' children: - label: '文档贡献指导' children: - - label: '文档贡献流程' + - label: '文档开发流程' href: './contribution_process.md' - label: '文档仓库目录结构说明' href: './directory_structure_introductory.md' diff --git a/docs/zh/Contribute/contribution_process.md b/docs/zh/Contribute/contribution_process.md index 4dcd3e2996dea5d20879c7a197394658748c29d6..377c3ac15b7e8c8d72993bf454e0bb42e0ac2dc5 100644 --- a/docs/zh/Contribute/contribution_process.md +++ b/docs/zh/Contribute/contribution_process.md @@ -1,30 +1,42 @@ -# 文档贡献流程 +# 文档开发流程 ## 概述 -本文档围绕文档是否发布在文档中心、新增/删除手册与文档、修改文档等场景,为文档开发者明确贡献流程。本文档中的示例均以中文文档为例,英文文档逻辑类似。 +本文档围绕新增文档,修改文档,删除文档三个场景,为开发者明确文档开发流程。本文档中的示例均以中文文档为例,英文文档逻辑类似。 -若需了解更详细的文档开发规范,请参考[文档仓库目录结构说明](./directory_structure_introductory.md),[menu文件写作规范](./menu_specifications.md)。英文文档贡献指导请详见[英文文档贡献指导](./english_doc_contribute.md)。若需了解在 Gitee 仓提交 issue 以及 PR 的具体指导,请详见[openEuler开源社区贡献指南](./openEuler开源社区贡献指南.md)。 +若需了解更详细的文档开发规范,请参考[文档仓库目录结构说明](./directory_structure_introductory.md),[menu文件写作规范](./menu_specifications.md)。英文文档贡献指导请详见[英文文档贡献指导](./english_doc_contribute.md)。若需使用 Git 提交 PR 以及 issue 的具体指导,请详见[openEuler开源社区贡献指南](./openEuler开源社区贡献指南.md)。 -## 文档发布在文档中心 +## 新增文档 -在 openEuler/docs 和 openEuler/SIG组名-docs 中,docs 目录中存放的内容将会被呈现在官网上。 +### 文档发布在文档中心 -### 新增手册 +1. 克隆文档仓到本地 -若开发者希望新增一本手册,以在虚拟化场景下新增《OpenStack 用户手册》为例,可参考以下操作步骤: + 要新增文档,开发者需要先明确存放相关内容的文档仓库是哪个。一般来讲,要确定新增内容该合并到哪个仓库,可以先看相关特性由哪个sig组负责维护,对应的sig组名-docs,就是存放新增内容的仓库。例如,《OpenStack用户指南》存放在 [openstack-docs](https://gitee.com/openeuler/openstack-docs) 仓。 -> 说明:《OpenStack 用户手册》由 OpenStack SIG 维护,存于 openEuler/openstack-docs 仓库。 + 如果是与系统安装升级或管理员指南相关的内容,属于通用配置,在 [docs](https://gitee.com/opengauss/docs) 仓统一维护。 -1. 为《OpenStack 用户手册》创建存放目录 - 若要在仓库存放《OpenStack 用户手册》,先进入 openEuler/openstack-docs 仓库的 docs 目录。该目录下的 zh 和 en 文件夹分别存放中文、英文文档,需要根据手册语言,在对应的文件夹内创建一个新的文件夹来存放《OpenStack 用户手册》。 +2. 在合适的目录下新建文档 - > 说明:openEuler/openstack-docs 仓库仅维护一本手册,所以无需在 /zh 或 /en 目录下新建文件夹。 + 文档仓克隆完成后,要先在仓库里找到合适的目录,然后在该目录下新增文档。具体目录可根据该新增文档在文档中心呈现的目录层级来找。 -2. 维护手册菜单文件 - 在手册目录下创建`_menu.md`文件,以此维护手册内部文档的导航结构。 + 例如,如果开发者想在《安装指南》中新增一个章节介绍多种安装方式,则需要在 [docs](https://gitee.com/opengauss/docs) 仓的 [Server > InstallationUpgrade > Installation](https://gitee.com/wu-donger/docs/tree/2503/docs/zh/Server/InstallationUpgrade/Installation) 目录下新建 `Installation-Modes.md`。因为《安装指南》相关内容属于通用文档,因此在docs仓统一进行维护。并且《安装指南》呈现在文档中心的服务器场景(Server)下的安装升级(InstallationUpgrade)类别下。 - _menu.md 文件内容示例: + ![image](figures/安装指南显示.jpg) + ![image](figures/安装指南gitee.jpg) + + 如果开发者想在《OpenStack用户指南》中新增一个章节介绍devstack,则需要在 [openstack-docs](https://gitee.com/openeuler/openstack-docs) 仓里新建 `devstack.md`。因为 OpenStack 相关特性是由 openstack SIG 维护,并且 openstack-docs 仓库仅维护一本手册,所以无需在细分目录。 + + ![image](figures/openstackgitee.jpg) + + 如果开发者不只是想在现有手册中新增一个章节,而是想新增一本完整的手册,则需要新建一个文件夹用来存放该手册下所有的章节。例如,如果开发者想在服务器场景(Server)下的安装升级(InstallationUpgrade)类别下,新增《升级指南》,则需要在 [docs](https://gitee.com/opengauss/docs) 仓的 [Server > InstallationUpgrade](https://gitee.com/wu-donger/docs/tree/2503/docs/zh/Server/InstallationUpgrade/Installation) 目录下新建 `Upgrade`。 + + ![image](figures/升级指南显示.jpg) + ![image](figures/升级指南gitee.jpg) + +3. 关联章节至对应手册 + + 新建文档后,为确保新增章节能正确显示,需在`_menu.md`文件里添加对该文档的引用。例如,开发者在 [openstack-docs](https://gitee.com/openeuler/openstack-docs) 仓里新建`devstack.md`后,需要在 [_menu.md](https://gitee.com/openeuler/openstack-docs/blob/openEuler-25.03/docs/zh/_menu.md) 中添加对`devstack.md`文档的引用。该`_menu.md`通常在新增文档的同级目录下存放。 ```yaml --- @@ -32,6 +44,8 @@ children: - label: '安装指导' children: + - label: 'devstack' + href: './install/devstack.md' - label: 'antelope' href: './install/antelope.md' - label: '操作及管理指导' @@ -41,15 +55,34 @@ --- ``` - 其中 label 指定文档节点显示名称,href 指定文档链接。 + 如果开发者不只是想在现有手册中新增一个章节,而是想新增一本完整的手册,则需要为该手册创建一个`_menu.md`文件。 -3. 灵活安排文档存放 - 手册中的 markdown 文档可依据业务逻辑存放在不同的文件夹下,此操作不做强制要求,开发者可按需处理。 +4. 关联手册至对应场景 -4. 关联手册至对应场景 - 在新增手册后,为确保该手册能在菜单导航中被访问,需要在对应业务场景的`_menu.md`文件里添加对它的引用。所有业务场景的`_menu.md`文件都在 openEuler/docs 代码仓中进行统一维护。 + 如果是新增一本完整手册的场景,除了上述步骤,还需要在对应场景的`_menu.md`文件中添加对手册的引用。换句话说,当开发者创建了新手册的`_menu.md`文件后,必须把这个文件的引用,添加到某个场景的`_menu.md`文件中,这样才能让新手册在相应场景中得以展示。 + + 下面给出两个示例进行说明,示例一: + + 如果开发者想在服务器场景下新增《升级指南》,则需要对 [docs](https://gitee.com/opengauss/docs) 仓 Server 目录下的 [_menu.md](https://gitee.com/openeuler/docs/blob/25.03/docs/zh/Server/_menu.md) 文件进行修改: + + ```yaml + --- + label: '服务器' + children: + - label: '发行说明' + children: + - reference: './Releasenotes/Releasenotes/_menu.md' + - label: '快速入门' + children: + - reference: './Quickstart/Quickstart/_menu.md' + - label: '安装升级' + children: + - reference: './InstallationUpgrade/Installation/_menu.md' + - reference: './InstallationUpgrade/Upgrade/_menu.md' + --- + ``` - 以《OpenStack 用户手册》为例,由于它归属于虚拟化场景,则需要对 openEuler/docs 仓库下的 /docs/zh/Virtualization/_menu.md 文件进行修改,将《OpenStack 用户手册》的引用添加进去。 + 如果开发者想在虚拟化场景下新增《OpenStack用户指南》,则需要对 [docs](https://gitee.com/opengauss/docs) 仓 Virtualization 目录下的 [_menu.md](https://gitee.com/openeuler/docs/blob/25.03/docs/zh/Virtualization/_menu.md) 文件进行修改: ```yaml --- @@ -63,66 +96,93 @@ --- ``` -### 新增文档 +5. 发布在文档中心 + + 提交文档修改的 P R后,doc SIG maintainer和各特性 SIG maintainer 会进行检视。只有当他们都审核通过,PR 才能合入。每晚8点至10点系统会自动构建,构建完成后,修改内容就会在官网显示。 + +### 文档不在文档中心发布 + +如果开发者所创作的文档内容,暂时不适合推广或尚不成熟,目前无需发布在文档中心,也可先提交至 [docs](https://gitee.com/opengaussa/docs) 仓的 [archive](https://gitee.com/openeuler/docs/tree/25.03/archive) 目录中。等到需要发布时,再将其移至合适的目录。这类文档同样需要遵循写作规范。 + +> 注意:提交至 archive 目录的文档,按计划未来会发布到文档中心,若长时间无人维护,将会被清理。 + +## 修改文档 + +文档修改分为以下三种情况: + +- 若需对现有文档内容进行修改,则需要找到文档的存放位置,并对其内容进行相应调整。 +- 若需对手册内各章节的目录结构进行修改,则需要找到对应手册的`_menu.md`,并对其内容进行相应调整。 +- 若需对文档中心各场景下的呈现结构进行修改,则需要找到对应场景的`_menu.md`,并对其内容进行相应调整。 -若开发者希望在现有手册里添加文档,以在《OpenStack 用户手册》下新增一篇文档 devstack.md 为例,可按以下步骤操作: +关于如何找到文档和`_menu.md`文件的存放位置,在[新增文档](#新增文档)章节有比较详细的介绍。 -1. 新增文档 - 需将新增文档放置于对应的手册目录中,如中文文档 devstack.md 放在 openEuler/openstack-docs/docs/zh(OpenStack 用户手册中文目录)。 +下面给出两个示例进行说明,示例一: -2. 更新菜单引用 - 存放好文档后,要确保它能在手册菜单中被访问到。需要修改《OpenStack 用户手册》的`_menu.md`文件,该文件通常位于手册目录下。打开`_menu.md`文件,添加对 devstack.md 文档的引用,这样用户就能在菜单导航中找到并访问该新增文档了。 +![image](figures/安装在服务器.jpg) + +如图所示,当前《安装指南》的章节设置中,“安装在服务器”作为首个章节显示。若开发者希望将“安装在树莓派”置于“安装在服务器”之上,需找到《安装指南》对应的 [menu.md](https://gitee.com/openeuler/docs/blob/25.03/docs/zh/Server/InstallationUpgrade/Installation/_menu.md) 文件,并对其进行修改: ```yaml --- -label: 'OpenStack 用户手册' +label: '安装指南' +ismanual: 'Y' +description: '安装 openEuler 操作系统' children: - - label: '安装指导' + - label: '安装在树莓派' + href: './install-pi.md' children: - - label: 'devstack' - href: './install/devstack.md' - - label: 'antelope' - href: './install/antelope.md' - - label: '操作及管理指导' + - label: '安装准备' + href: './Installation-Preparations1.md' + - label: '安装在服务器' + href: './install-server.md' children: - - label: '安全指南' - href: './security/security-guide.md' + - label: '安装准备' + href: './installation-preparations.md' --- ``` -### 内容修改 - -如果仅对原有文档内容进行修改,不需要修改`_menu.md`文件或修改目录结构。 - -### 删除手册 +示例二: -删除手册的具体步骤如下: +![image](figures/安装升级.jpg) -1. 删除与手册对应的文件夹,该文件夹内包含的所有文档以及`_menu.md`文件也将一并删除。 -2. 在手册对应场景的`_menu.md`文件里,移除其中对手册的引用内容。 - -例如,如果要删除 《OpenStack 用户手册》,则需要在虚拟化场景的`_menu.md`文件中,删除对《OpenStack 用户手册》的引用。 +如图所示,当前在服务器场景下,《安装指南》显示在《升级指南》之前。若开发者希望将《升级指南》调整至前面显示,需找到服务器场景对应的 [menu.md](https://gitee.com/openeuler/docs/blob/25.03/docs/zh/Server/_menu.md) 文件并加以修改: ```yaml --- -label: '虚拟化' +label: '服务器' children: -- label: '虚拟化平台' - children: - - reference: './Virtualization/_menu.md' - - reference: './StratoVirt/_menu.md' - - reference: 'https://gitee.com/openeuler/openstack-docs/blob/openEuler-25.03/docs/zh/_menu.md' + - label: '快速入门' + children: + - reference: './Quickstart/Quickstart/_menu.md' + - label: '安装升级' + children: + - reference: './InstallationUpgrade/Upgrade/_menu.md' + - reference: './InstallationUpgrade/Installation/_menu.md' + - label: '系统管理' + children: + - reference: './Administration/Administrator/_menu.md' + - reference: './Administration/sysMaster/_menu.md' + - reference: './Administration/CompaCommand/_menu.md' --- ``` -### 删除文档 +## 删除文档 + +删除文档的操作步骤如下: -删除文档的具体步骤如下: +1. 首先,确定想要删除的文档存放在何处,找到后将其删除。 +2. 接着,找到对应手册的`_menu.md`文件,在其中去掉对已删除章节的引用。 +3. 若开发者不只删除某本手册中的部分章节,而是要删除一整本手册,除上述操作外,还需找到对应场景的`_menu.md`文件,在里面删除对手册的引用。 -1. 删除对应的 markdown 文档。 -2. 在手册的`_menu.md`文件中,删除对文档的引用。 +关于如何找到文档和`_menu`文件的存放位置,在[新增文档](#新增文档)章节有比较详细的介绍。 -例如,如果要删除《OpenStack 用户手册》中的 devstack.md,则需要在对应的手册`_menu.md`下,删除对 devstack.md 文档的引用。 +下面给出示例进行说明: + +![image](figures/安装升级.jpg) + +如图所示,当前在虚拟化场景中,《OpenStack用户指南》设有专门章节对 devstack 进行介绍。 + +如果开发者要删除《OpenStack用户指南》中的 devstack 章节,首先要删除此章节对应的`.md`文件([devstack.md](https://gitee.com/openeuler/openstack-docs/blob/openEuler-25.03/docs/zh/install/devstack.md)),并在《OpenStack用户指南》的 [_menu.md](https://gitee.com/openeuler/openstack-docs/blob/openEuler-25.03/docs/zh/_menu.md) 下,删除对`devstack.md`文档的引用: ```yaml --- @@ -130,17 +190,23 @@ label: 'OpenStack 用户手册' children: - label: '安装指导' children: - - label: 'devstack' - href: './install/devstack.md' - - label: 'antelope' + - label: 'devstack' + href: './install/devstack.md' + - label: 'antelope'markdown href: './install/antelope.md' - - label: '操作及管理指导' - children: - - label: '安全指南' - href: './security/security-guide.md' --- ``` -## 文档不于文档中心发布 +如果开发者要将《OpenStack用户指南》全部删除,除了要删除与该手册相关的全部`.md`文件外,还需要在虚拟化场景的 [_menu.md](https://gitee.com/openeuler/docs/blob/25.03/docs/zh/Virtualization/_menu.md) 文件中,删除对《OpenStack 用户手册》的引用。 -如果文档不需要发布在文档中心,仅在gitee仓内存储,则放在文档仓与 docs 目录同级的 Archive 目录下。 +```yaml +--- +label: '虚拟化' +children: + - label: '虚拟化平台' + children: + - reference: './VirtualizationPlatform/Virtualization/_menu.md' + - reference: './VirtualizationPlatform/StratoVirt/_menu.md' + - reference: 'https://gitee.com/openeuler/openstack-docs/blob/openEuler-25.03/docs/zh/_menu.md' +--- +``` diff --git a/docs/zh/Contribute/figures/openstackgitee.jpg b/docs/zh/Contribute/figures/openstackgitee.jpg new file mode 100644 index 0000000000000000000000000000000000000000..abf6e87c05d355e822a004955965c4795a8651a5 Binary files /dev/null and b/docs/zh/Contribute/figures/openstackgitee.jpg differ diff --git "a/docs/zh/Contribute/figures/openstack\346\230\276\347\244\272.jpg" "b/docs/zh/Contribute/figures/openstack\346\230\276\347\244\272.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..ed1ec0c21bb5e7f23c451a942bfce5ff883bc409 Binary files /dev/null and "b/docs/zh/Contribute/figures/openstack\346\230\276\347\244\272.jpg" differ diff --git "a/docs/zh/Contribute/figures/\345\215\207\347\272\247\346\214\207\345\215\227gitee.jpg" "b/docs/zh/Contribute/figures/\345\215\207\347\272\247\346\214\207\345\215\227gitee.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..08f908ea27faa6f49e5efa3af5c83c36ddaf175c Binary files /dev/null and "b/docs/zh/Contribute/figures/\345\215\207\347\272\247\346\214\207\345\215\227gitee.jpg" differ diff --git "a/docs/zh/Contribute/figures/\345\215\207\347\272\247\346\214\207\345\215\227\346\230\276\347\244\272.jpg" "b/docs/zh/Contribute/figures/\345\215\207\347\272\247\346\214\207\345\215\227\346\230\276\347\244\272.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..7d6514b55e0a0303c7e0fb65deaae49acd1d35aa Binary files /dev/null and "b/docs/zh/Contribute/figures/\345\215\207\347\272\247\346\214\207\345\215\227\346\230\276\347\244\272.jpg" differ diff --git "a/docs/zh/Contribute/figures/\345\256\211\350\243\205\345\215\207\347\272\247.jpg" "b/docs/zh/Contribute/figures/\345\256\211\350\243\205\345\215\207\347\272\247.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..f76220c0c4bfd59a6acff7940d756bc7f1b6d65a Binary files /dev/null and "b/docs/zh/Contribute/figures/\345\256\211\350\243\205\345\215\207\347\272\247.jpg" differ diff --git "a/docs/zh/Contribute/figures/\345\256\211\350\243\205\345\234\250\346\234\215\345\212\241\345\231\250.jpg" "b/docs/zh/Contribute/figures/\345\256\211\350\243\205\345\234\250\346\234\215\345\212\241\345\231\250.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..90977793c851947e8e3c8b1dbe7339536943adb0 Binary files /dev/null and "b/docs/zh/Contribute/figures/\345\256\211\350\243\205\345\234\250\346\234\215\345\212\241\345\231\250.jpg" differ diff --git "a/docs/zh/Contribute/figures/\345\256\211\350\243\205\346\214\207\345\215\227gitee.jpg" "b/docs/zh/Contribute/figures/\345\256\211\350\243\205\346\214\207\345\215\227gitee.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..8486eeb321335042484d96b2ad75ec6996ad4d39 Binary files /dev/null and "b/docs/zh/Contribute/figures/\345\256\211\350\243\205\346\214\207\345\215\227gitee.jpg" differ diff --git "a/docs/zh/Contribute/figures/\345\256\211\350\243\205\346\214\207\345\215\227\346\230\276\347\244\272.jpg" "b/docs/zh/Contribute/figures/\345\256\211\350\243\205\346\214\207\345\215\227\346\230\276\347\244\272.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..795048c577020455011005576fa5cc0d43af4f8c Binary files /dev/null and "b/docs/zh/Contribute/figures/\345\256\211\350\243\205\346\214\207\345\215\227\346\230\276\347\244\272.jpg" differ diff --git a/docs/zh/Contribute/menu_specifications.md b/docs/zh/Contribute/menu_specifications.md index 21dc206dd7f716ebde16043c4498292428943439..6448da8f080ac98fe191a6838a23e2c3e6a569c7 100644 --- a/docs/zh/Contribute/menu_specifications.md +++ b/docs/zh/Contribute/menu_specifications.md @@ -117,4 +117,4 @@ children: - 顶层 label 指定场景名,例子中展示的是服务器场景。 - 服务器 children 下的 label 对应服务器场景下的一级目录,如发行说明、快速入门、安装升级、系统管理等。 -- 每个一级目录 children 下的 reference 表明引用,您可以使用该字段引用该目录下各本手册的`_menu.md`文件或二级目录,从而形成一个完整的“菜单树”。 \ No newline at end of file +- 每个一级目录 children 下的 reference 表明引用,您可以使用该字段引用该目录下各本手册的`_menu.md`文件或二级目录,从而形成一个完整的“菜单树”。