Doxygen提供了不同级别的自定义。微调部分讨论了如果您想对输出的外观和感觉进行微调时该怎么做。布局部分展示了如何重新排序和隐藏页面上的某些信息。 XML输出部分展示了如何根据Doxygen生成的XML输出生成您想要的任何输出。

微调

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

整体颜色

为了改变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是一个HTML片段，Doxygen通常用它来开始一个HTML页面。请注意，该片段以body标签结束，并且它包含一些形式为$word的命令。这些命令将由Doxygen即时替换。
footer.html是一个HTML片段，Doxygen通常用它来结束一个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将填写适当的特定语言标题。

您可以通过在XML文件中的navindex元素内移动选项卡元素来重新排序选项卡，甚至可以更改树结构。但是，不要更改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”的选项卡将选项卡分组到自定义组中。以下示例将上述选项卡放入标题为“我的组”的用户定义组中：

  <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: 表示页面的作者部分（仅用于man页面）。这是man页面的一个独立部分，文本类似于：Doxygen为My Project从源代码自动生成。这不应与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文档生成器连接的示例。

转到下一节或返回索引。