微调

以下小节描述了一些可以轻松调整的方面。

整体颜色

要更改 HTML 输出的整体颜色，Doxygen 提供了三个选项

分别用于更改颜色的色相、饱和度和伽马校正。

为了方便起见，GUI 前端 Doxywizard 提供了一个控件，可以让你实时查看更改这些选项值对输出效果的影响。

动态内容

为了使 HTML 输出更具交互性，Doxygen 提供了许多默认禁用的选项

启用 HTML_DYNAMIC_SECTIONS 将使 Doxygen 默认隐藏 HTML 中的某些内容（如图形），并允许读者按需展开这些部分。
启用 HAVE_DOT 和 INTERACTIVE_SVG，同时将 DOT_IMAGE_FORMAT 设置为 svg，将使 Doxygen 生成 SVG 图像，允许用户进行缩放和平移（这仅在图像大小超过一定尺寸时发生）。

页眉、页脚和样式表更改

要详细调整 HTML 输出的字体、颜色、边距或其他外观方面的细节，你可以创建一个不同的级联样式表。你还可以让 Doxygen 为它生成的每个 HTML 页面使用自定义的页眉和页脚，例如使输出符合你网站其他部分的样式。

为此，首先按如下方式运行 Doxygen：

doxygen -w html header.html footer.html customdoxygen.css

这将创建 3 个文件：

header.html 是 Doxygen 通常用来开始 HTML 页面的 HTML 片段。请注意，该片段以 body 标签结尾，并且包含一些形式为 $word 的命令。这些命令将在 Doxygen 运行时被替换。
footer.html 是 Doxygen 通常用来结束 HTML 页面的 HTML 片段。这里也可以使用特殊命令。这个文件包含到 www.doxygen.org 的链接以及 body 和 html 结束标签。
customdoxygen.css 是 Doxygen 使用的默认级联样式表。建议只查看此文件，并通过将你喜欢的某些设置放入单独的样式表中并通过 HTML_EXTRA_STYLESHEET 引用这些额外文件来覆盖它们。

你应该编辑这些文件，然后在配置文件中引用它们。

HTML_HEADER = header.html
HTML_FOOTER = footer.html
HTML_EXTRA_STYLESHEET = my_customdoxygen.css

注意: 不再推荐使用 HTML_STYLESHEET，因为它会使升级到新版本的 Doxygen 变得困难。请改用 HTML_EXTRA_STYLESHEET。

有关可在自定义页眉中使用的元命令的更多信息，请参阅 HTML_HEADER 标签的文档。

注意: 你不应将样式表放在 HTML 输出目录中。将其视为源文件。Doxygen 会为你复制它。; 如果你在自定义页眉中使用图像或其他外部内容，你需要自己确保它们最终出现在 HTML 输出目录中，例如编写一个脚本运行 Doxygen，然后将图像复制到输出目录。

警告: 升级到新版本的 Doxygen 后，页眉和页脚的结构可能会发生变化，因此如果你正在使用自定义页眉或页脚，升级后可能无法再生成有效的输出。

更改页面布局

在某些情况下，你可能希望更改输出的结构方式。不同的样式表或自定义页眉和页脚在这种情况下没有帮助。

Doxygen 提供的解决方案是一个布局文件，你可以修改它，Doxygen 将使用它来控制呈现哪些信息、以何种顺序呈现以及在一定程度上如何呈现信息。布局文件是一个 XML 文件。

默认布局可以使用以下命令由 Doxygen 生成：

doxygen -l

可以选择指定布局文件的名称，如果省略，将使用 DoxygenLayout.xml。

下一步是在配置文件中提及布局文件（另请参阅 LAYOUT_FILE）。

LAYOUT_FILE = DoxygenLayout.xml

要更改布局，你只需编辑布局文件。

文件顶层结构如下所示：

<doxygenlayout version="1.0">
  <navindex>
    ...
  </navindex>
  <class>
    ...
  </class>
  <namespace>
    ...
  </namespace>
  <concept>
    ...
  </concept>
  <file>
    ...
  </file>
  <group>
    ...
  </group>
  <directory>
    ...
  </directory>
</doxygenlayout>

XML 文件的根元素是 doxygenlayout，它有一个名为 version 的属性，将来将用于处理不向后兼容的更改。

第一部分由 navindex 元素标识，代表了显示在每页 HTML 页面顶部的导航标签的布局。同时，它还控制着当 GENERATE_TREEVIEW 启用时导航树中的项目。每个标签由 XML 文件中的一个 tab 元素表示。

你可以通过将 visible 属性设置为 no 来隐藏标签。你还可以通过将 title 属性的值指定为所需标题来覆盖标签的默认标题。如果标题字段为空字符串（默认），Doxygen 将填充适当的语言特定标题。

你可以通过在 navindex 元素内移动 XML 文件中的 tab 元素来重新排序标签，甚至更改树结构。但是，不要更改 type 属性的值。只支持一组固定的类型，每种类型代表一个指向特定索引的链接。

你还可以使用名称为 "user" 的类型添加自定义标签。这是一个示例，展示了如何添加一个标题为 "Google" 并指向 www.google.com 的标签：

  <navindex>
    ...
    <tab type="user" url="http://www.google.com" title="Google"/>
    ...
  </navindex>

url 字段也可以是相对 URL。如果 URL 以 @ref 开头，链接将指向一个有文档的实体，例如类、函数、组或相关页面。假设我们使用 @page 和标签 mypage 定义了一个页面，那么一个指向该页面的标签，标题为 "My Page"，看起来如下：

  <navindex>
    ...
    <tab type="user" url="@ref mypage" title="My Page"/>
    ...
  </navindex>

你还可以使用类型为 "usergroup" 的标签将多个标签分组到一个自定义组中。以下示例将上述标签放入一个标题为 "My Group" 的用户定义组中：

  <navindex>
    ...
    <tab type="usergroup" title="My Group">
      <tab type="user" url="http://www.google.com" title="Google"/>
      <tab type="user" url="@ref mypage" title="My Page"/>
    </tab>
    ...
  </navindex>

组可以嵌套以形成层次结构。

默认情况下，导航树中的 usergroup 条目是一个链接，指向包含组内容的着陆页。你可以使用 url 属性链接到不同的页面，就像你可以为 <tab> 元素所做的那样，并且可以使用 url="[none]" 防止任何链接，即：

   <tab type="usergroup" title="Group without link" url="[none]">
   ...
   </tab>

navindex 之后的元素代表了 Doxygen 生成的不同页面的布局：

class 元素代表为有文档的类、结构体、联合体和接口生成的所有页面的布局。
namespace 元素代表为有文档的命名空间（以及 Java 包）生成的所有页面的布局。
concept 元素代表为有文档的概念生成的所有页面的布局。
module 元素代表为有文档的 C++ 模块生成的所有页面的布局。
file 元素代表为有文档的文件生成的所有页面的布局。
group 元素代表为有文档的组（或主题）生成的所有页面的布局。
directory 元素代表为有文档的目录生成的所有页面的布局。

上述页面元素中的每个 XML 元素代表一条特定的信息。有些信息片段可以出现在每种类型的页面中，而有些则特定于某种类型的页面。Doxygen 将按照它们在 XML 文件中出现的顺序列出这些片段。

以下通用元素可用于每个页面：

briefdescription: 代表页面上的简要描述。
detaileddescription: 代表页面上的详细描述。

以下通用元素可用于除 directory 页面外的每个页面：

authorsection: 代表页面的作者部分（仅用于手册页）。这是手册页的一个独立部分，包含类似于 Generated automatically by Doxygen for My Project from the source code. 的文本。这不应与 Doxygen 命令 \author 或 \authors 混淆，后者在详细描述中生成一个作者段落。

以下通用元素可用于除 concept 页面外的每个页面：

memberdecl: 代表页面上成员的快速概览（成员声明）。此元素根据成员列表的类型拥有子元素。本文档中未详细列出可能的子元素，但元素的名称应能很好地指示该元素代表的成员类型。

以下通用元素可用于除 concept 和 module 页面外的每个页面：

memberdef: 代表页面上的详细成员列表（成员定义）。与 memberdecl 元素一样，此元素也有多个可能的子元素。

class 页面具有以下特定元素：

includes: 代表获取此类定义所需的包含文件。
inheritancegraph: 代表类的继承关系。请注意，CLASS_GRAPH 选项决定了继承关系是基类和派生类的列表还是一个图形。
collaborationgraph: 代表类的协作图。
allmemberslink: 代表指向类所有成员列表的链接。
usedfiles: 代表从中提取类文档的文件列表。

concept 页面具有以下特定元素：

includes: 代表获取此类定义所需的包含文件。
definition: 代表概念的定义

file 页面具有以下特定元素：

includes: 代表此文件中包含的 #include 语句列表。
includegraph: 代表文件的包含依赖图。
includedbygraph: 代表文件的被包含依赖图。
sourcelink: 代表指向此文件源代码的链接。

module 页面有一个特定的 exportedmodules 元素，它代表从此模块导出的模块。

group 页面有一个特定的 groupgraph 元素，它代表显示组之间依赖关系的图。

类似地，directory 页面有一个特定的 directorygraph 元素，它代表基于目录内文件的 #include 关系显示目录之间依赖关系的图。

有些元素有 visible 属性，通过将其属性值设置为 no 可以从生成的输出中隐藏该片段。你也可以使用配置选项的值来确定可见性，方法是在其名称前加上美元符号，例如：

  ...
  <includes visible="$SHOW_INCLUDE_FILES"/>
  ...

这主要是为了向后兼容而添加的。请注意，visible 属性只是 Doxygen 的一个提示。如果某个片段没有相关信息可用，即使将其设置为 yes，也会被省略（即不会生成空部分）。
并非所有元素都在布局文件中显示了 visible 属性，但无论如何都可以使用此属性（默认值为 visible="yes"）。

有些元素有 title 属性。此属性可用于自定义 Doxygen 将用作该片段标题的文本。

请注意，从 doxygen 1.13.1 版本和布局文件 2.0 版本开始，Doxygen 将为用户定义布局文件中缺失的元素插入默认值。这允许引入新元素，而无需更新用户定义的布局文件即可使其出现。对于较旧的 Doxygen 或布局版本，缺失的元素将被视为不可见。

使用 XML 输出

如果上述两种方法仍然无法提供足够的灵活性，你还可以使用 Doxygen 生成的 XML 输出作为基础来生成你想要的输出。为此，请将 GENERATE_XML 设置为 YES。

XML 输出包含一个名为 index.xml 的索引文件，该文件列出了 Doxygen 提取的所有项目，并引用其他 XML 文件以获取详细信息。索引的结构由模式文件 index.xsd 描述。所有其他 XML 文件由名为 compound.xsd 的模式文件描述。如果你喜欢一个大的 XML 文件，可以使用 XSLT 文件 combine.xslt 将索引和其他文件合并。

你可以使用任何 XML 解析器来解析这些文件，或使用 Doxygen 源代码分发版中 addon/doxmlparser 目录下的解析器。查看 addon/doxmlparser/doxmlparser/index.py 和 addon/doxmlparser/doxmlparser/compound.py 了解解析器的接口（它由 generatedDS 生成，并遵循在 templates/xml 中找到的 XML 模式文件 index.xsd 和 compound.xsd）。查看 addon/doxmlparser/examples 获取示例。

使用 doxmlparser 的优点在于它只将索引文件读入内存，然后只隐式加载通过索引导航到的 XML 文件。因此，即使对于非常大的项目，即使将所有 XML 文件作为单个大型 DOM 树读取会超出内存，它也能正常工作。

请参阅Breathe 项目，了解一个使用 Python 的 Doxygen XML 输出并将其与 Sphinx 文档生成器桥接的示例。

转到下一节或返回索引。