自定义页面

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 命令，我们可以在各种主题之间添加链接，这样做将自动开始填充我们的树形视图。

如果您发现您的树更像一堆树叶，那么您可以通过查看子分页来解决此问题。

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