本文将介绍如何使用Doxygen、Breath和Sphinx生成整洁美观的项目文档。
前言
本来只是从前辈们的老代码里了解到Doxygen这个东西，顺藤摸瓜查了一下，发现内容和功能不少，但是生成的网页太几把丑了，有一种千禧年的美。因此又顺着查了一下，发现了Sphinx这个东西，也就是ROS2官方文档的生成工具，非常的符合现代审美。但是这个东西是用来生成Python文档的，并不支持生成C++文档，所以需要一个Breathe插件来实现对C++的支持，并不麻烦。
为什么要使用文档生成工具？
对比传统文档（静态网页）来说，每次改动代码都要求重新编辑文档，非常不便于维护，容易造成代码文档分离的过时问题等。使用文档生成工具后，可以将文档编写的工作融入于代码编写，一方面是提高了文档工作的效率，另一方面也增加了代码的可读性。
为什么选择Doxygen？对比其他工具，比如Javadoc、JSDoc、MkDocs等，功能较为局限，语言支持少，Doxygen支持多种语言，生成的文档也非常简洁直观且全面，抛开美观性不谈是最好的选择。而Sphinx是一个可高度自定义的文档工具，缺点在于不支持C++语言，因此需要使用Breathe插件来做中间桥梁。
Doxygen注释规范
首先，在每个源文件开头应添加文件注释，如：
/**
* @file main.c
* @brief 主程序文件
* @details 包含程序入口和主要逻辑
* @author Syzygy5593
* @version 1.0.0
* @date 2025-05-03
* @copyright Copyright (c) 2025
*/结构体，函数和类的注释都应该注释在代码上方，如：
/**
* @brief 面包结构体
* @details 包含面包的基本信息
*/
typedef struct {
int amount; ///< 数量
char type[50]; ///< 类型
float cost; ///< 价格
} Bread;对变量的注释可以在上方也可以在右侧，如：
/** 面包1 */
int Bread1;
int Bread2; ///< 面包2
int Bread3; //!< 面包3以下是doxygen一些常用的参数段（参考文献）
| 命令 | 描述 | 示例 |
|---|---|---|
| @file | 文件名 | @file main.c |
| @brief | 简要描述 | @brief 主函数 |
| @details | 详细描述 | @details 程序入口点 |
| @param | 函数参数 | @param x 横坐标 |
| @return | 返回值 | @return 计算结果 |
| @retval | 特定返回值 | @retval NULL 内存分配失败 |
| @note | 注意事项 | @note 非线程安全 |
| @warning | 警告信息 | @warning 可能导致溢出 |
| @see | 参考链接 | @see other_function() |
| @code/@endcode | 代码块 | @code … @endcode |
| @image | 插入图片 | @image html diagram.png |
Doxygen文档生成示例
以生成 >此项目< 的文档为例，这是一个很简单的项目示例
需要安装以下：
sudo apt-get install doxygen
sudo apt-get install python3-sphinx先在项目根目录生成Doxyfile文件：
doxygen -g在新生成的Doxyfile里，搜一下关键词，修改这些参数（文件比较长，需要修改的已经标注行数了）：
# 项目名称，在35行
PROJECT_NAME = "Example"
# 输出文件夹，在61行
OUTPUT_DIRECTORY = docs/doxygen
# 需要生成代码的文件路径，在867行
INPUT = src
# 是否递归搜索源代码目录，在946行
RECURSIVE = YES
# 是否生成HTML、LaTex和xml文件
# 如果只是为了生成Sphinx文档，可以只生成xml
# 分别在1216 1793 2097行
GENERATE_HTML = YES
GENERATE_LATEX = NO
GENERATE_XML = YES保存之后，生成Doxygen文档：
mkdir -p docs/doxygen
doxygen Doxyfile到此为止，在你的输出文件夹就可以找到index.html并打开了，接下来使用breathe和sphinx对文档进行美化
Sphinx文档生成示例
首先需要安装sphinx、breathe和rtd主题（ros2官方文档同款）：
pip3 install sphinx breathe
pip3 install sphinx_rtd_theme创建一个目录用于存放sphinx的文件，这里以docs/sphinx为例，然后在这个目录下初始化：
mkdir -p docs/sphinx
cd docs/sphinx
sphinx-quickstart接着按照提示进行配置，项目名称、作者和版本等
在生成的文件中找到conf.py进行配置：
# 添加扩展
extensions = ['breathe']
# breathe的配置
breathe_projects = { "Example": "../doxygen/xml" }
breathe_default_project = "Example"
# 更换主题
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]然后按照rst的语法，编写index.rst的内容即可，例如：
Example Documentation
=======================
.. toctree::
:maxdepth: 2
:caption: File Documentation
files
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`接着新建files.rst，可以直接用doxygenfile来自动生成文档
这里分离rst是便于后期修改，以及方便后期加入其他文档
Source Files
============
BaseClass.h
------------
.. doxygenfile:: BaseClass.h
:project: Example
BaseClass.cpp
------------
.. doxygenfile:: BaseClass.cpp
:project: Example
DerivedClass.h
------------
.. doxygenfile:: DerivedClass.h
:project: Example
DerivedClass.cpp
------------
.. doxygenfile:: DerivedClass.cpp
:project: Example
Utils.h
------------
.. doxygenfile:: Utils.h
:project: Example
Utils.cpp
------------
.. doxygenfile:: Utils.cpp
:project: Example
main.cpp
------------
.. doxygenfile:: main.cpp
:project: Example
完成以上步骤后，生成文档
make html之后就可以在build文件夹下找到html文件了，打开就是一个漂亮的文档～
RST语法简单入门
rst和python类似，需要较为严格的格式（空行、空格）
标题格式如下，分割线长于标题文字即可
==============
一级标题
==============
二级标题
==============
三级标题
--------------
四级标题
^^^^^^^^^^^^^^
五级标题
""""""""""""""
六级标题
**************文字样式如下
*斜体*
**粗体**
- 列表1
- 列表2
名词解释
定义内容
分割线
---------代码格式如下，开头需要有两个英文冒号，后接空行，之后是代码部分，代码部分结束后还需要一个空行
::
#include <stdio.h>
行内代码 ``code``其他的方案
在寻找这一套方案的过程中，偶然看到了单纯美化doxygen css的方案，比如>这个方案<，虽然选择不是很多，但是也会比doxygen原生设计好看一万倍。