Doxygen 文档模块化复用实战:用 `@include{doc}` 与 `raise` 实现 Markdown 章节嵌套与层级提升
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
这个文件本身并不独立成页,而是作为内容片段被上层文档引用。注意它的两个特征:
- 它以 Markdown 一级标题
# Included Section 1.1开头,这意味着它自带章节结构; - 它自己又通过
@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"。两组不同的包含路径最终都收敛到了正确的三层结构,验证了:
raise的层级提升是按被包含文件自身的标题级别逐级累加的(sub.md一级标题 →##;subsub.md一级标题再 →###);@include{doc}支持递归嵌套——sub.md里还可以继续@include{doc}其他片段;- 同一份
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 等输入控制项管理。
七、实战建议:构建可维护的模块化文档
综合以上语法与实现,推荐如下落地模式:
- 拆分片段:把跨页面复用的内容(协议说明、安装步骤、兼容性矩阵)拆成独立的
.md片段文件,每个片段以适中的标题级别开头(建议不超过#/##); - 统一入口:主文档通过
@include{doc,raise=1} fragment.md引入片段,用raise把片段标题对齐到父文档层级;若担心多次引入后\ref锚点冲突,追加prefix选项; - 递归组合:片段内部可以继续
@include{doc}更小的子片段(如testing/sub.md嵌套subsub.md),形成"文档组件"体系; - 自动化验证:参照仓库
testing/062与testing/063的模式,为每个包含场景准备一份期望 XML 输出,配合 Doxygen 测试框架持续回归,防止层级或锚点回归; - 注意约束:被包含文档不要写注释符号,标题级数要为
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。