LVGL文档构建目录结构优化方案

背景介绍

在LVGL开源图形库项目中，文档构建系统的目录结构一直采用传统布局方式。随着项目发展，开发团队发现当前的文档构建目录结构存在一些优化空间，特别是关于源代码、生成文件和临时文件的组织方式。

现有问题分析

当前LVGL文档构建系统存在几个值得关注的问题：

1. 文档源文件和生成文件分散在不同目录层级
2. 临时文件处理不够规范
3. 构建系统与文档内容耦合度过高
4. 目录结构不符合现代文档构建的最佳实践

这些问题可能导致构建过程不够清晰、维护困难，也不利于新贡献者快速理解项目结构。

优化方案设计

经过团队讨论，提出了基于Linux文档构建目录结构的优化方案：

docs/               # 文档源代码目录
├── output/         # 所有生成文件
│   ├── html/       # HTML格式输出
│   └── latex/      # LaTeX格式输出
└── tmp/            # 临时构建目录

这个设计方案具有以下技术优势：

1. 层次清晰：所有文档相关内容都集中在docs目录下
2. 隔离性好：源文件、生成文件和临时文件严格分离
3. 扩展性强：方便添加新的输出格式
4. 符合惯例：采用类似Linux内核文档的结构

技术实现细节

Sphinx构建适配

由于Sphinx构建工具对源目录中的额外.rst文件处理不够友好，解决方案是：

1. 将Sphinx的源目录指向docs/tmp/
2. 通过Python脚本将所需源文件从docs/复制到临时目录
3. 构建过程中自动排除output和tmp目录

构建命令改进

优化后的clean命令行为：

python build.py clean

该命令将：

• 仅清除生成文件
• 保留源文件不变
• 可以安全地清理临时构建目录

兼容性考虑

方案实施需要考虑以下兼容性因素：

1. GitHub Actions工作流需要更新输出目录引用
2. 文档自动化部署系统的路径配置
3. 开发者本地环境的构建脚本调整

经过评估，这些改动都集中在有限的配置文件中，迁移成本可控。

方案优势总结

1. 更规范的目录结构：符合开源项目文档管理的最佳实践
2. 更好的可维护性：源文件与生成文件分离，便于版本控制
3. 更清晰的构建过程：临时文件处理更加透明
4. 更少的顶层目录：项目根目录更加整洁

实施建议

对于计划采用类似文档结构的项目，建议：

1. 分阶段实施目录结构调整
2. 更新相关CI/CD配置文件
3. 在贡献者文档中说明新的构建流程
4. 提供迁移脚本帮助现有贡献者过渡

这种目录结构优化不仅适用于LVGL项目，也可作为其他开源项目文档系统设计的参考方案。