自定义页面

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 中，用逗号分隔，但这随着我们手册的构建可能会变得很烦人，因此我们将只更改它来引用我们的 manual 文件夹：

INPUT = manual/

并设置

RECURSIVE = YES

以确保随着我们添加 manual 的任何子目录，我们将创建更多的组织和内容。

侧边栏树状视图

随着您的手册规模扩大，您可能还需要一个漂亮的树状视图来显示您在手册中的位置，以便保持条理清晰。这很容易设置，只需开启它：

GENERATE_TREEVIEW = YES

在您的 Doxyfile 中。

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

如果您注意到您的树更像一堆落叶而不是树状结构，您可以通过查看 Subpaging 来解决这个问题。

本次讨论应该为您如何构建可扩展的手册以丰富您的文档提供一些方向，接下来您可能想要自定义您的布局。