自定义页面

Doxygen 也可用于创建不属于库/程序 API 的自定义页面。这些页面的目的是使用您认为用户可能觉得有用的任何其他内容来丰富您的文档。

要创建自定义页面，请使用支持的文件扩展名之一：.dox、.txt 或 .md。Doxygen 会将 .dox 或 .txt 文件视为 C/C++ 源文件，并将 .md 文件视为 Markdown 文件。

对于 .dox 或 .txt 文件，可以使用单个 Doxygen 注释，如下所示

manual/index.dox

/** \mainpage 我的库手册
- 构建
- 基础知识
- 示例
*/

您会注意到使用了 \mainpage 命令，该命令告诉 Doxygen 将此页面用作主页。对于其他页面，请在其前面加上 \page 命令。

默认情况下，Doxygen 不会知道这些自定义文件，因此我们需要通过 Doxyfile 中的 INPUT 属性来告知它。对于上述示例，请将此行添加到您的 Doxyfile

INPUT = manual/index.dox

接下来，我们可能想要添加有关如何构建项目的说明，因此我们创建 manual/building/index.dox。当您阅读更多文档时，您会发现 Doxygen 支持 HTML 标签的子集，因此我们可以编写以下内容

/** \page 构建
 
<h2>Linux</h2>
<p>
构建此项目的简单方法是使用 cmake，克隆存储库，cd 到项目的根目录并运行
</p>
 
<pre>
<code>
mkdir my_build
cmake -S . -B my_build
cd my_build
cmake --build .
</code>
</pre>
 
*/

当然，您也可以使用流行的 Markdown 表示法执行相同的操作

# Building

## Linux

A simple way to build this project is with cmake, clone the repository,
cd into the root of the project and run:

    mkdir my_build
    cmake -S . -B my_build
    cd my_build
    cmake --build .

扩展规模

自动添加文件

此时，我们现在可以将 manual/building/index.dox 通过逗号分隔的方式添加到我们的 INPUT 中，但是随着我们构建手册，这可能会随着时间的推移变得令人恼火，相反，我们将只更改它以引用我们的手册文件夹

INPUT = manual/

并设置

RECURSIVE = YES

以确保当我们创建更多组织和内容时，会添加手册的任何子目录。

侧边栏树状视图

随着手册规模的扩大，您可能还希望有一个漂亮的树状视图来显示您在手册中的位置，以便保持井井有条。这很容易设置，通过以下方式打开它

GENERATE_TREEVIEW = YES

在您的 Doxyfile 中。

您会记得我们的 manual/index.dox 文件非常平淡，没有任何指向任何地方的链接，通过使用 \ref 命令，我们可以在各个主题之间添加链接，这样做会自动开始填充我们的树状视图。

如果您注意到您的树更像是一堆叶子，那么您可以通过查看子页面来解决此问题。

此讨论应该为您提供有关如何构建可扩展手册以丰富文档的一些指导，从这里您可能想要自定义您的布局。