如何在单个Doxygen页面中按子目录组织VHDL模块文档？

方案1：结合@addgroup与@ingroup构建自定义层级 #

• 给每个顶层模块定义主组，用@addgroup <模块名>，同时在组描述里明确层级关系
• 子模块/设计单元通过@ingroup <父模块组名>关联到主组，Doxygen会自动在组页面生成成员列表，模拟层级结构
• 示例代码：

  --! @addgroup UART_MODULE UART通信模块
  --! @{
  --! 包含发送器、接收器、波特率发生器三个子单元
  --! @}
  
  --! @ingroup UART_MODULE
  --! UART发送器子模块
  entity uart_tx is
    ...
  end entity;
  

• 配置里开启GROUP_GRAPHS = YES，可生成组间层级关系图，接近「Design unit Hierarchy」效果

方案2：利用@defgroup嵌套实现层级 #

• 用@defgroup定义父组和子组，通过@ingroup指定父子关系，构建嵌套层级
• 示例代码：

  --! @defgroup UART_TOP UART顶层模块
  --! @{
  --! @defgroup UART_TX_SUB UART发送器子模块
  --! @ingroup UART_TOP
  --! @defgroup UART_RX_SUB UART接收器子模块
  --! @ingroup UART_TOP
  --! @}
  

• 这种方式能在Doxygen组页面直接展开嵌套结构，和「Design unit Hierarchy」的层级展示逻辑一致

方案3：自定义页面整合模块内容 #

• 用@page命令创建模块单页面文档，通过@ref引用各设计单元，手动编排层级结构
• 示例代码：

  --! @page uart_page UART通信模块文档
  --! ### 模块层级结构
  --! - UART_TOP
  --!   - UART_TX_SUB
  --!   - UART_RX_SUB
  --!   - BAUD_GEN_SUB
  --!
  --! ### 各单元详情
  --! @ref uart_tx
  --! @ref uart_rx
  

• 完全自定义页面内容，精准控制层级展示，适合对文档结构要求高的场景

补充配置优化 #

• 在Doxygen配置文件中设置：
  • VHDL_SUPPORT = YES：确保VHDL语法解析正常
  • EXTRACT_ALL = YES：强制提取所有设计单元，避免遗漏
  • GENERATE_TREEVIEW = YES：侧边栏生成层级树，方便导航

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