Windows 环境下使用 Doxygen 生成 Python 文档

🚀 一、安装准备

1. ‌安装 Doxygen‌

   • 官网下载安装包：https://www.doxygen.nl/download.html25
   • 双击安装（默认选项即可）

2. ‌安装依赖工具‌

   • ‌Graphviz‌（生成图表）：
     官网下载：https://graphviz.org/download/4
     安装时勾选 ‌Add Graphviz to system PATH‌8
   • ‌doxypypy‌（Python 解析插件）：

     pip install doxypypy # 关键插件

⚙️ 二、配置文件设置

1. ‌生成配置文件‌
   打开命令提示符执行：

   doxygen -g Doxyfile

2. ‌修改关键配置‌（用文本编辑器打开 Doxyfile）：

   PROJECT_NAME = "YourProject"
   OUTPUT_DIRECTORY = docs  # 文档输出目录
   INPUT = src              # Python 源码路径
   RECURSIVE = YES          # 扫描子目录
   EXTRACT_ALL = YES        # 提取无注释代码
   OUTPUT_LANGUAGE = Chinese  # 中文文档
   OPTIMIZE_OUTPUT_JAVA = YES  # 优化Python输出
   HAVE_DOT = YES           # 启用Graphviz图表
   DOT_PATH = "C:\\Program Files\\Graphviz\\bin"  # Graphviz安装路径
   FILTER_PATTERNS = *.py="doxypypy -a -c"  # 关键：启用Python解析

⚠️ 注意：DOT_PATH 需替换为您的实际安装路径（如 D:\\graphviz\\bin）。

         2.1 若需扫描多个不相邻目录：   

INPUT = /path1 /path2 /path3  # 空格分隔多个路径

        2.2 排除特定目录

EXCLUDE = /path/to/exclude  # 排除单个目录
EXCLUDE_PATTERNS = */test/* # 通配符排除所有test子目录

        2.3 文件类型过滤

FILE_PATTERNS = *.cpp *.h *.py  # 只处理指定扩展名文件

        2.4 符号链接处理

SYMLINKS = YES  # 跟随符号链接扫描

📝 三、Python 注释规范

1. 模块注释 (module.py)

"""!
@package module_name
@brief 模块功能说明
"""

2. 类注释

class Example:
    """!
    @brief 类功能描述
    @details 补充说明（可选）
    """
    def method(self, param: int):
        """!
        @brief 方法说明
        @param param 参数解释
        @return 返回值说明
        """
        return param * 2

‌语法要点‌：

• 使用 """! 作为 Doxygen 识别标记（普通 """ 不会被解析）8
• @param 需匹配参数名，@return 描述返回值

🖥️ 四、生成文档

1. ‌执行生成命令‌
   在 Doxyfile 所在目录运行：

   doxygen Doxyfile

2. ‌查看文档‌
   打开 docs/html/index.html 浏览 HTML 文档

若需生成 ‌CHM 文档‌，需额外安装 HTML Help Workshop 并配置 GENERATE_HTMLHELP=YES4。

⚠️ 五、常见问题解决

🔗 辅助工具推荐

1. ‌VSCode 插件‌
   • 安装 Doxygen Documentation Generator：自动生成注释模板
2. ‌GUI 配置工具‌
   运行 doxywizard.exe 可视化编辑配置（安装目录内）

💡 ‌提示‌：复杂项目可通过 EXCLUDE_PATTERNS = */tests/* 排除测试目录。