自定义输出

目录

• 小调整
  • 整体颜色
  • 导航
  • 动态内容
  • 页眉、页脚和样式表更改
• 更改页面布局
• 使用 XML 输出

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

小调整

接下来的小节描述了一些可以通过少量努力进行调整的方面。

整体颜色

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

• HTML_COLORSTYLE_HUE
• HTML_COLORSTYLE_SAT
• HTML_COLORSTYLE_GAMMA

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

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

导航

默认情况下，Doxygen 将显示一个跨越页面全宽的标题区域，并在内容下方，其中导航树作为每个 HTML 页面的左侧边栏。

这对应于 Doxyfile 中的以下设置

• DISABLE_INDEX = YES
• GENERATE_TREEVIEW = YES
• FULL_SIDEBAR = NO

您可以使用以下命令使侧边栏跨越页面的整个高度

• DISABLE_INDEX = YES
• GENERATE_TREEVIEW = YES
• FULL_SIDEBAR = YES

您还可以用每个 HTML 页面顶部的选项卡替换导航树，这对应于以下设置

• DISABLE_INDEX = NO
• GENERATE_TREEVIEW = NO

甚至可以使用两种形式的导航

• DISABLE_INDEX = NO
• GENERATE_TREEVIEW = YES

如果您已经使用外部索引（即启用了以下选项之一：GENERATE_HTMLHELP、GENERATE_ECLIPSEHELP、GENERATE_QHP 或 GENERATE_DOCSET），那么您也可以禁用所有索引，如下所示

• DISABLE_INDEX = YES
• GENERATE_TREEVIEW = NO

动态内容

为了使 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 属性的值来覆盖选项卡的默认标题。如果 title 字段是空字符串（默认值），则 Doxygen 将填充适当的特定于语言的标题。

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

您还可以使用名为“user”的类型添加自定义选项卡。这是一个示例，展示了如何添加一个标题为“Google”的选项卡，该选项卡指向 www.google.com

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

url 字段也可以是相对 URL。如果 URL 以 @ref 开头，则该链接将指向已记录的实体，例如类、函数、组或相关页面。假设我们使用 @page 定义了一个带有标签 mypage 的页面，那么指向此页面的标签为“我的页面”的选项卡将如下所示

  <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 元素表示为记录的概念生成的所有页面的布局。
• file 元素表示为记录的文件生成的所有页面的布局。
• group 元素表示为记录的组（或主题）生成的所有页面的布局。
• directory 元素表示为记录的目录生成的所有页面的布局。

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

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

briefdescription

表示页面上的简短描述。

detaileddescription

表示页面上的详细描述。

authorsection

表示页面的作者部分（仅用于 man 页面）。这是 man 页面的一个独立部分，其中包含类似如下的文本：由 Doxygen 为我的项目从源代码自动生成。 这不应与 Doxygen 命令 \author 或 \authors 混淆，后者会在详细描述中生成作者段落。

以下通用元素可用于除概念页面之外的每个页面

memberdecl

表示页面上成员的快速概述（成员声明）。此元素具有每个成员列表类型的子元素。文档中未详细列出可能的子元素，但元素的名称应该很好地指示元素表示的成员类型。

memberdef

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

类页面具有以下特定元素

includes

表示获取此类的定义所需的包含文件。

inheritancegraph

表示类的继承关系。请注意，CLASS_GRAPH 选项决定了继承关系是基类和派生类的列表还是图形。

collaborationgraph

表示类的协作图。

allmemberslink

表示指向类的所有成员列表的链接。

usedfiles

表示从中提取类文档的文件列表。

概念页面具有以下特定元素

includes

表示获取此类的定义所需的包含文件。

definition

表示概念的定义

文件页面具有以下特定元素

includes

表示此文件中包含的 #include 语句列表。

includegraph

表示文件的包含依赖关系图。

includedbygraph

表示文件的被包含依赖关系图。

sourcelink

表示指向此文件源代码的链接。

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

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

某些元素具有 visible 属性，可以通过将属性值设置为 "no" 来隐藏生成的输出中的片段。您还可以使用配置选项的值来确定可见性，方法是使用其名称并以美元符号为前缀，例如。

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

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

某些元素具有 title 属性。此属性可用于自定义 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 文档生成器连接起来。

转到下一节或返回索引。