大型项目中Doxygen能否实现Examples板块嵌套分级目录结构？

Doxygen默认的Examples板块会扁平化展示所有识别到的示例文件，不会自动继承EXAMPLE_PATH下的文件夹层级，直接创建子目录或者多路径指定无法实现嵌套效果，可通过以下方案实现需求：

前置基础配置 #

先确认Doxygen配置文件中以下基础项已正确设置：

• GENERATE_TREEVIEW = YES 启用侧边栏树状视图
• EXAMPLE_PATH = 你的示例根目录路径 只需指定示例根目录即可
• EXAMPLES_RECURSIVE = YES 开启递归扫描根目录下所有子目录的示例文件
• EXAMPLE_PATTERNS = *.cpp *.c *.h 按需填写你需要识别的示例文件后缀

方案1：分组功能实现（无需修改布局文件） #

利用Doxygen原生的Grouping分组功能关联示例文件，即可自动生成层级结构：

1. 在项目公共头文件或专门的Doxygen说明文件中定义顶层示例分组：

/**
 * @defgroup examples 示例合集
 * @brief 所有功能模块的示例代码汇总
 */

2. 为每个子分类定义子分组，绑定到顶层示例分组下：

/**
 * @defgroup examples_triangle 三角形示例
 * @ingroup examples
 * @brief 三角形相关功能的示例代码
 */

/**
 * @defgroup examples_rectangle 矩形示例
 * @ingroup examples
 * @brief 矩形相关功能的示例代码
 */

// 其他分类以此类推

3. 在每个示例文件的头部添加绑定标记，将文件归到对应子分组：

// 以triangle_1.cpp为例
/**
 * @example triangle_1.cpp
 * @ingroup examples_triangle
 * @brief 三角形面积计算基础示例
 */

配置完成后重新生成文档，即可在侧边栏Modules板块下看到嵌套的示例层级，如需将该层级放到Examples板块下，可参考方案2的布局修改步骤。

方案2：自定义示例页实现（完全可控层级结构） #

如果需要完全自定义Examples板块的展示结构，可通过自定义页面+修改布局的方式实现：

1. 新建专门的Doxygen说明文件（如examples_index.md），编写自定义的层级结构：

/**
 * @page custom_examples 示例代码
 * 
 * 按功能分类的示例代码如下：
 * 
 * @section triangle_sec 三角形示例
 * - @ref triangle_1.cpp "三角形基础计算示例"
 * - @ref triangle_2.cpp "三角形碰撞检测示例"
 * 
 * @section rectangle_sec 矩形示例
 * - @ref rectangle_1.cpp "矩形旋转示例"
 * - @ref rectangle_2.cpp "矩形缩放示例"
 * 
 * @section circle_sec 圆形示例
 * - 其他示例以此类推
 */

2. 生成并修改Doxygen布局文件：

• 执行命令doxygen -l生成默认布局文件DoxygenLayout.xml
• 打开布局文件，找到默认的Examples标签配置：
  <tab type="examples" visible="yes" title="Examples" intro=""/>
• 将其替换为自定义示例页的绑定配置：
  <tab type="user" visible="yes" title="Examples" url="@ref custom_examples"/>

3. 回到Doxygen主配置文件，添加布局文件配置：
   LAYOUT_FILE = DoxygenLayout.xml
   重新生成文档后，侧边栏的Examples板块就会展示你自定义的嵌套层级结构。

注意事项 #

• 所有示例文件必须添加@example标记，否则Doxygen不会将其识别为示例文件，无法生成对应的跳转链接
• 两种方案都兼容Doxygen 1.9.1版本，无需升级工具

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