如何将嵌套Git子模块的多份README.md整合到单份Doxygen文档？

我之前处理过类似的嵌套子模块Doxygen文档生成需求，这里给你一套可行的配置方案，能让根目录README做主页，同时完整集成所有子模块的文档和代码链接：

1. 强制指定根目录README为主页 #

别只写USE_MDFILE_AS_MAINPAGE = README.md，给根目录的README加上相对路径前缀，让Doxygen明确识别它：

USE_MDFILE_AS_MAINPAGE = ./README.md

这样就不会被子模块里的同名README.md覆盖主页设置了。

2. 精准控制要扫描的文件范围 #

在Doxyfile里配置INPUT和EXCLUDE_PATTERNS，确保根目录和所有子模块的代码、README都被纳入，同时排除无关文件：

# 明确列出根目录和所有子模块路径
INPUT = ./ ./LIBRARY-1 ./LIBRARY-2 ./ETC.

# 排除Git目录、构建产物这些不需要的内容
EXCLUDE_PATTERNS = */.git/* */build/* */test/*

根据你的项目实际结构调整INPUT里的子模块路径，确保每个子模块都被包含。

3. 让子模块README成为文档的一部分 #

Doxygen默认会解析Markdown文件，所以只要子模块的README.md在INPUT范围内，就会被自动解析。你还可以在根目录README里添加指向子模块README的链接，让文档结构更清晰：

## 子模块参考文档
- [Library 1 详细说明](LIBRARY-1/README.md)
- [Library 2 使用指南](LIBRARY-2/README.md)

Doxygen会自动把这些相对路径链接转换成文档内部的跳转链接，用户能直接从主页跳转到子模块文档。

4. 确保跨模块代码元素能互相链接 #

要让不同子模块的类、函数等符号互相跳转，得把所有子模块的头文件目录加入INCLUDE_PATH：

INCLUDE_PATH = ./ ./LIBRARY-1/include ./LIBRARY-2/include ./ETC./include

根据你的项目头文件实际存放路径修改这个配置，这样Doxygen就能找到所有符号的定义，生成正确的交叉引用链接。

5. 兜底方案：给子模块README加标记防冲突 #

如果还是出现子模块README抢主页的情况，直接在子模块的README.md开头加个Doxygen页面标记，明确它是子页面：

/*! \page library1 Library 1 文档
 * 这里是Library 1的详细说明内容...
 */

这样Doxygen会把这个文件解析为名为library1的独立页面，绝对不会干扰根目录的主页设置。

按照这些步骤配置后，你就能生成一份从根目录README开始的单一集成文档，既保留了所有子模块的README信息，又能让跨模块的代码元素正常互相链接。

内容的提问来源于stack exchange，提问作者Chris Marshall