Doxygen 文档模块化复用实战:用 `@include{doc}` 与 `raise` 实现 Markdown 章节嵌套与层级提升

原创2026-10-10 23:32:451,641 阅读
文章标签:文档CLI开发工具

Doxygen 文档模块化复用实战:用 @include{doc} 与 raise 实现 Markdown 章节嵌套与层级提升

导读:当项目文档出现大量重复章节时,逐一复制粘贴既难维护又容易产生漂移。Doxygen 提供的 @include{doc} 命令可以把独立的 Markdown / Doxygen 文档当作可复用片段,像"拼积木"一样按需嵌入主文档,配合 raise 选项还能自动提升被包含文件的标题层级,让嵌套文档自然融入父文档的章节树。本文以仓库中 testing/sub.md 及其配套测试为线索,完整讲解 @include{doc 的选项语法、底层实现(\iraise/\iprefix)和端到端验证方法,帮助你构建可维护的模块化文档体系。

一、从 testing/sub.md 说起:一个被包含的文档片段

仓库中的 testing/sub.md 是一份非常典型的"被包含文档片段",全文只有三行有效内容:

# Included Section 1.1

Some text in sub.md.

@include{doc,raise=1} subsub.md

这个文件本身并不独立成页,而是作为内容片段被上层文档引用。注意它的两个特征:

  1. 它以 Markdown 一级标题 # Included Section 1.1 开头,这意味着它自带章节结构;
  2. 它自己又通过 @include{doc,raise=1} subsub.md 二次嵌套引用了另一个片段 testing/subsub.md,后者同样以 # Included Section x.1.1 标题开头——这形成了"文档嵌套文档"的层级结构。

这正是模块化文档的核心思路:把共享内容(如接口说明、通用步骤、平台差异描述)拆成独立小文件,由不同主文档按需引入,避免多份拷贝之间的不一致。Doxygen 将每个 Markdown 文件转换为一个页面,而 @include{doc} 则负责把这些页面级内容"摘出来"嵌入到任意位置,而不是仅仅作为独立页面存在。

二、\include 命令家族与 doc 选项的定位

@include{doc} 是 Doxygen 的 \include 命令在 doc 选项下的形态。在 doc/commands.dox 中,\include 的官方语义是"将源码文件作为一段代码块包含进来",等价于把文件内容插入文档块并用 \code 与 \endcode 包裹:

\include example.cpp       // 相当于 \code ... \endcode 包裹整个文件

它的主要用途是避免"由多个源文件/头文件组成的示例块"出现代码重复。与之配套的还有:

  • \dontinclude:不直接显示内容,配合 \line、\skip、\skipline、\until 做逐行引用;
  • \snippet{doc,...}:只引用文件中用特殊标记圈出的片段;
  • \includelineno:带行号包含,已标记为 obsolete,仅为向后兼容保留。

\include 支持的 option 包括 lineno、doc、local,以及 strip/nostrip:

选项 作用
lineno 为包含的代码启用行号显示
doc 将文件当作文档而非代码处理,这是本文的核心
local 让 Doxygen 把代码解释为出现在当前类/命名空间作用域,而非全局作用域
strip 总是隐藏被包含代码中的特殊注释,覆盖 STRIP_CODE_COMMENTS 配置
nostrip 总是显示被包含代码中的特殊注释

其中 strip/nostrip 在 doc 模式下不生效——文档本来就是按注释语义解析的。文件查找路径由配置文件中的 EXAMPLE_PATH 指定,若文件名在示例路径集合中不唯一,可携带部分绝对路径来消歧。

三、@include{doc} 语法:嵌入文档与 raise 层级提升

当使用 doc 选项时,文件内容不再被当作代码块,而是作为文档直接展开到当前位置。此时额外的两个选项变得关键:

3.1 raise:整体提升被包含文档的章节层级

在 doc/commands.dox 中,官方对 raise 的说明如下:

\include{doc,raise=1} file.dox

会把 file.dox 中所有 1 级 \section 当作 2 级 \subsection、2 级 \subsection 当作 3 级 \subsubsection,以此类推。对于 Markdown 文档,效果等价于把 # 一级标题当作 ## 二级标题。这正是 testing/sub.md 中 raise=1 的含义:sub.md 自己的 # Included Section 1.1 被提升为 ##,从而挂在主文档的 # Section 1 之下,而 subsub.md 的 # Included Section x.1.1 再次提升为 ###,形成正确的三级嵌套。

3.2 prefix:为被包含章节的标签加前缀避免冲突

除 raise 外,doc 模式还有 prefix 选项(见 doc/commands.dox):

\include{doc,prefix=fn_} file.dox

会把 file.dox 中的 \section s1 视同 \section fn_s1 处理。这样同一份片段被多次引入时,各个 \ref/\link 锚点标签不会互相覆盖。raise 与 prefix 可组合使用,且两者的行为在源码中由同一套内部机制实现(见下文第五节)。

3.3 使用约束

官方文档在 doc/commands.dox 特别提醒:被包含的文档内容不应含有注释符号(comment signs),否则它们会原样出现在生成的文档里。此外,@include 家族的 doc 模式与 \snippet{doc,raise=N} 共享同一套层级提升逻辑(对比测试见 testing/063_main.md),因此本文的结论同样适用于 \snippet{doc}。

四、端到端验证:testing/062 的完整调用链

要直观理解 @include{doc,raise=N} 的效果,最好的途径是仓库自带的回归测试 062。入口文件 testing/062_main.md 开头用 HTML 注释声明了测试目标:

<!--
// objective: test @include{doc} command with raise option
// check: md_062__main.xml
-->

其正文结构为:

[TOC]

Some text in main.md

# Section 1
@include{doc,raise=1} sub.md

# Section 2
## Subsection 2.1
@include{doc,raise=2} subsub.md

测试期望输出存放在 testing/062/md_062__main.xml,以 Doxygen XML 输出形式记录了标题树的最终形态。对照源文件与期望 XML,可以清晰看到两次 raise 的作用:

源位置 源标题 引用指令 期望输出层级
主文档 # Section 1 Section 1 — <sect1>
sub.md 的 # Included Section 1.1 Included Section 1.1 @include{doc,raise=1} sub.md <sect2>
subsub.md 的 # Included Section x.1.1 Included Section x.1.1 @include{doc,raise=1} 内部再套 subsub.md(来自 sub.md 内引用) <sect3>
主文档 # Section 2 下的 ## Subsection 2.1 Subsection 2.1 — <sect2>
subsub.md 再次被 @include{doc,raise=2} subsub.md 直接引用 Included Section x.1.1 raise=2 <sect3>

期望 XML 中 md_062__main.xml 的 detaileddescription 结构为:sect1 "Section 1" → sect2 "Included Section 1.1" → sect3 "Included Section x.1.1",随后 sect1 "Section 2" → sect2 "Subsection 2.1" → sect3 "Included Section x.1.1"。两组不同的包含路径最终都收敛到了正确的三层结构,验证了:

  1. raise 的层级提升是按被包含文件自身的标题级别逐级累加的(sub.md 一级标题 → ##;subsub.md 一级标题再 → ###);
  2. @include{doc} 支持递归嵌套——sub.md 里还可以继续 @include{doc} 其他片段;
  3. 同一份 subsub.md 可以被不同的父文档以不同 raise 值重复引入而不互相干扰。

五、底层原理:\iraise 与 \iprefix 内部命令

raise 与 prefix 并非在渲染阶段才做特殊处理,而是由词法扫描器在解析文档时提前注入内部命令实现的。仓库内部文档 doc_internal/commands_internal.md 记录了这两个命令:

  • \iraise <amount>:内部命令,将后续章节层级提高指定数量。例如处理 \iraise 1 之后,\section s1 会被当作 \subsection s1 处理。该命令在 \include{doc} 携带 raise 选项时被自动插入;
  • \iprefix "<label>":内部命令,为后续 \ref/\link 的标签引用加上前缀,\iprefix "pf_" 之后 \ref s1 等价于 \ref pf_s1。该命令在 \include{doc} 携带 prefix 选项时被自动插入。

两者的引入版本均为 Doxygen 1.11.0,这也解释了为什么 testing/062、testing/063 这类用例会被放在仓库中做持续回归。

在实现层面,src/commentcnv.l 展示了包含动作发生时如何构造内部命令串:

\ifile "<absFileName>" \iline <lineNr>
\iraise <raiseLevel>        // 仅当 raiseLevel > 0 时插入
\iprefix "<raiseLabel>"     // 仅当 raiseLabel 非空时插入
\ilinebr

扫描器维护了 raiseLevel/raiseIncrement 与 raiseLabel/raisePrefix 两组状态:进入被包含文件时,当前累计的 raise 值与前缀标签被写入内部命令,同时文件的旧状态被压栈;离开文件时(src/commentcnv.l)恢复旧值并再次输出 \iraise/\iprefix 以便回到主文档的原始层级。由于这些状态与文件上下文绑定,多次嵌套包含、不同 raise 值的混用都能被正确还原——这正是 062 测试中三级嵌套得以成立的原因。

六、配套要点:Markdown 标题层级、TOC 与文件发现

6.1 标题层级上限

raise 的工作依赖于 Doxygen 的 Markdown 标题语法。按 doc/markdown.dox 的说明,行首 # 的个数决定标题级别,最多支持 6 级(行尾可跟任意数量 # 作为闭合标记):

# This is a level 1 header

### This is level 3 header #######

因此在使用 raise 时要注意被包含文件与父文档的级数预算:若父文档已用到 4 级标题,再对片段 raise=2,很可能触及 6 级上限之外。实践中建议被包含片段统一使用 1~2 级标题,把 3 级及以上的空间留给主文档。

6.2 [TOC] 与 TOC_INCLUDE_HEADINGS

testing/062_main.md 顶部使用了 <a href="https://link.gitcode.com/i/68f55264067315c2e166a113205673a1" target="_blank">TOC] 标记,Doxygen 会在页面起始处生成目录(与 \tableofcontents 等价)。注意 [doc/markdown.dox 的提醒:只有 TOC_INCLUDE_HEADINGS 配置大于 0 时,Markdown 标题才会被纳入目录。被 @include{doc} 嵌入的标题同样受此配置影响,若期望目录中展示全部嵌套章节,应确保该配置足够大(默认情况下该值需显式设置)。

6.3 Markdown 文件如何被发现

@include{doc} 引用的文件与普通 Markdown 页面走同一套文件发现逻辑:Doxygen 会处理输入目录中的 .md/.markdown 文件,每个文件默认转换为一个页面;若文件以 \defgroup、\dir 等专用命令开头则不单独成页,README.md 在子目录中默认作为目录文档(详见 doc/markdown.dox)。在自定义扩展名场景下,需要通过配置文件中的 EXTENSION_MAPPING 把自定义后缀映射到 md 解析器。也就是说,一个片段文件既可以被独立生成页面,也可以只被 @include{doc} 当作内容来源——Doxygen 不会因为"被包含"就跳过其页面生成,如需隐藏可结合 EXCLUDE 等输入控制项管理。

七、实战建议:构建可维护的模块化文档

综合以上语法与实现,推荐如下落地模式:

  1. 拆分片段:把跨页面复用的内容(协议说明、安装步骤、兼容性矩阵)拆成独立的 .md 片段文件,每个片段以适中的标题级别开头(建议不超过 # / ##);
  2. 统一入口:主文档通过 @include{doc,raise=1} fragment.md 引入片段,用 raise 把片段标题对齐到父文档层级;若担心多次引入后 \ref 锚点冲突,追加 prefix 选项;
  3. 递归组合:片段内部可以继续 @include{doc} 更小的子片段(如 testing/sub.md 嵌套 subsub.md),形成"文档组件"体系;
  4. 自动化验证:参照仓库 testing/062 与 testing/063 的模式,为每个包含场景准备一份期望 XML 输出,配合 Doxygen 测试框架持续回归,防止层级或锚点回归;
  5. 注意约束:被包含文档不要写注释符号,标题级数要为 raise 预留空间,同时确认 TOC_INCLUDE_HEADINGS 与 EXAMPLE_PATH 配置正确。

从 testing/sub.md 这样一份三行的小片段出发,借助 @include{doc 的 raise/prefix 选项与 \iraise/\iprefix 内部机制,即可把零散文档组织成结构清晰、可复用、可测试的模块化体系——这正是 Doxygen 文档工程中"一次编写、多处引用、自动对齐层级"的关键能力。

参考路径索引:关联文档 testing/sub.md、嵌套片段 testing/subsub.md、调用入口 testing/062_main.md、期望输出 testing/062/md_062__main.xml、命令语法 doc/commands.dox、Markdown 标题规则 doc/markdown.dox、内部命令定义 doc_internal/commands_internal.md、词法实现 src/commentcnv.l。

登录后查看全文
doxygen