基于 CMake 的文档构建流程优化

rfcs/Docs/基于 CMake 的文档构建流程优化.md

@@ -0,0 +1,143 @@
+# 基于 CMake 的文档构建流程优化
+
+|领域 | 基于 CMake 的文档构建流程优化 | 
+|---|--------------------------------|
+|提交作者 | RedContritio | 
+|提交时间 | 2023-11-28 | 
+|版本号 | V1.0 | 
+|依赖飞桨版本 | develop 分支 | 
+|文件名 | 基于 CMake 的文档构建流程优化.md | 
+
+# 一、概述
+## 1、相关背景
+
+随着文档所需的表现形式、处理逻辑的日益多样化与复杂化，[飞桨文档仓库](https://github.com/PaddlePaddle/docs) 文档源文件类型逐渐复杂，文档处理逻辑也较为零散。
+
+| 文档源文件类型 | 数量 |
+| --- | --- |
+| md | 1493 |
+| rst | 1489 |
+| py | 52 |
+| ipynb | 44 |
+| 其他 | ... |
+
+此外，由于处理逻辑往往含有副作用，如 [PR: 文档构建会导致 git 仓库产生大量文件改动](https://github.com/PaddlePaddle/docs/issues/6232) 所述，构建操作会破坏仓库的可维护性，增加开发者本地构建仓库的成本，并间接导致开发者贡献意愿降低。
+
+## 2. 功能目标
+
+### 2.1 cmake 工具引入
+
+引入 cmake 工具，将构建过程限制在特定的 build 目录中，以消除构建对版本控制的破坏性。
+
+### 2.2 构建脚本逻辑更新
+
+更新原有构建脚本，添加指定输入输出目录的用法，以提高对新构建流程的适应性与可迁移性。
+
+根据不同构建脚本的功能，进行纵向拆分，消除不同构建模块的横向依赖关系。
+
+### 2.3 构建流程重构
+
+对在 `python` 或 `shell` 文件中硬编码的构建流程进行提取，通过 cmake 维护依赖关系，提高并行性和可维护性。
+
+# 二、飞桨现状
+
+## 1、文档生成
+
+飞桨当前的英文文档基于 `CAPITools` 从源代码注释提取，中文文档则独立保存在 `paddle/docs` 目录下。
+
+英文文档生成过程中，通过 `ci_scripts/gendoc.sh` 脚本进行多线程的提取与生成。
+
+## 2、markdown 转换 html
+
+飞桨现在对 markdown 的转换均生成至当前目录下，目录内文件数量翻倍。
+
+转换使用 `.pre-commit-hooks/convert_markdown_into_html.py` 文件于 pre-commit 中进行。
+
+
+# 三、设计思路与实现方案
+
+由于文档构建流程修改的影响面较大，将编译流程优化分解为以下阶段：
+
+1. 前期 解耦并引入工具：
+
+    保留原有的文档构建逻辑，仅对文档构建脚本的调用采用 cmake 进行组织，并修复文档预览时部分页面跳转可能离开预览状态，访问官网的情况。
+    在构建过程中，将仓库相关的文件（包含文档源文件与脚本文件）均复制到 `build/` 目录中，以隔离脚本文件副作用，在生成文档后，将 `build/output/` 拷贝回 `output/`。
+
+    - 全局检查文档内超链接，对硬编码到 paddlepaddle 官网的超链接进行更新；
+
+    - 分析现有构建流程，引入 cmake 工具加入构建流程。
+
+2. 中期 构建脚本升级：
+
+    对原有的文档构建流程进行升级，使其适配 cmake 构建流程，不复制脚本文件，仅将中间构建文件生成到 `build/` 目录中。
+
+    - 对于现有的文档构建脚本，支持输入输出路径可变，使适配独立构建的流程；
+
+    - 对文档构建脚本进行整合与重构，实现全局构建脚本的统一管理；
+
+    - 对文档构建流程依赖关系进行整理，使支持多线程文档构建，加快构建速度。
+
+3. 后期 收尾检查：
+
+    对优化后流程生成结果与原流程生成结果进行对比，确认一致并经过相关工作人员 approve 后，完成文档构建流程的切换。
+
+# 四、测试与验收的考量
+
+[飞桨文档仓库](https://github.com/PaddlePaddle/docs) 构建流程统一化，构建速度提高。
+
+# 五、排期规划
+
+整个任务的规划步骤如下：
+
+1. 对原有影响预览页面跳转封闭性的超链接进行排查，保证预览的安全性；
+2. 引入 cmake，重整原有构建脚本的调用流程；
+3. 逐项更新原有构建脚本，使支持独立构建；
+4. 分析原有构建流程的依赖关系，使支持多线程构建；
+5. 整理构建脚本，对构建脚本进行重构与整理，降低脚本维护成本；
+
+# 六、影响面
+
+- 引入 cmake
+
+    1. 对用户的影响
+
+        不涉及
+
+    2. 对开发者的影响
+
+        对需要修改、维护文档构建流程的开发者，增加了 cmake 学习成本
+
+    3. 对官网文档的影响
+
+        无
+
+- 更新原有构建脚本
+
+    1. 对用户的影响
+
+        不涉及
+
+    2. 对开发者的影响
+
+        - 流程优化过程中，对开发者无影响
+        - 流程优化后，开发者增加新的处理流程时，需要与其他构建脚本保持相同的用户公共接口，以便接入 cmake 构建流程
+
+    3. 对官网文档的影响
+
+        无
+
+- 整理依赖关系使支持多线程构建
+
+    1. 对用户的影响
+
+        不涉及
+
+    2. 对开发者的影响
+
+        - 流程优化过程中，对开发者无影响
+        - 流程优化后，开发者增加新的处理流程时，开发者和 reviewer 都需要考虑该流程的依赖关系，以避免破坏多线程构建，导致偶发错误
+
+    3. 对官网文档的影响
+
+        当依赖关系整理后，需要进行细致的 review，以保证依赖关系正确，否则可能导致多线程构建出现错误
+