如何合并Doxygen代码片段，优化文档代码块展示？

核心方案：带标记的snippet+可测试完整文件+视觉合并优化 #

直接针对你遇到的所有痛点，用以下步骤实现可自动化测试的示例代码+干净的文档展示：

1. 编写可编译测试的示例文件 #

创建完整的可编译示例文件（比如examples/demo_usage.cpp），用Doxygen的snippet标记包裹需要在文档中展示的核心代码，无关的#include、测试断言等放在标记外：

#include <iostream>
#include "../src/my_lib.h"
#include <catch2/catch_all.hpp>  // 测试框架头文件，不影响文档展示

/// [core_usage]
// 这部分是要展示的核心代码
MyLib calc;
calc.add(10, 20);
std::cout << "Sum: " << calc.get_result() << std::endl;

calc.divide(30, 5);
std::cout << "Quotient: " << calc.get_result() << std::endl;
/// [core_usage]

// 自动化测试代码，文档中不展示
\cond TEST_ONLY
TEST_CASE("MyLib functional test") {
    REQUIRE(calc.get_result() == 6);
}
\endcond

这个文件可以直接加入你的测试套件编译运行，保证示例代码和实际功能同步。

2. 在Doxygen注释中引用snippet #

在你的类/函数的Doxygen文档中，用@snippet提取标记的核心代码，完全避开多余的#include：

/**
 * @brief 基础算术运算类
 *
 * 快速上手示例：
 * @snippet examples/demo_usage.cpp core_usage
 */
class MyLib {
    // 类实现...
};

3. 解决多个snippet分散的问题 #

如果需要展示多段逻辑相关的代码（比如分步骤的示例），默认Breathe会生成多个独立代码块，可通过两种方式合并：

• 方式1：用单个大snippet标记：把所有需要展示的代码放在同一个/// [tag]和/// [tag]之间，提取后自然是单个代码块。
• 方式2：视觉合并CSS：如果必须拆分snippet（比如代码分属不同文件），在Sphinx的_static/custom.css中添加样式：

div.breathe-code-block + div.breathe-code-block {
    margin-top: -12px;
    border-top: none;
}

然后在conf.py中加载该样式：

html_css_files = ['custom.css']

这样相邻的代码块会无缝衔接，视觉上和单个代码块一致。

4. 彻底替代\dontinclude #

snippet标记完全不需要依赖搜索模式或硬编码行号，只提取标记内的内容，不会把搜索规则显示在文档中，完美解决\dontinclude的痛点。

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