如何通过Doxygen生成变量与函数使用位置关系的可视化图形？

Doxygen对Python的静态解析能力弱于C/Java这类静态语言，按以下步骤配置即可拿到你要的调用关系树形可视化图：

前置依赖 #

先本地安装Graphviz工具，Doxygen的所有关系图都靠它的dot引擎渲染；再通过pip安装doxypy，用来做Python语法的预过滤，补全Doxygen原生解析的缺陷。

核心Doxyfile配置修改 #

打开你项目的Doxyfile配置文件，逐项修改以下参数：

• 语言适配配置
  • OPTIMIZE_OUTPUT_PYTHON = YES：开启Python语法专属优化，老版本Doxygen没有这个选项的话，改成OPTIMIZE_OUTPUT_JAVA = YES也可兼容
  • EXTRACT_ALL = YES：强制提取所有代码成员，避免无注释的自定义函数、变量被跳过
  • EXTRACT_PRIVATE = YES：提取下划线开头的私有函数、类私有变量
  • EXTRACT_STATIC = YES：提取模块级的全局函数、全局变量
  • FILTER_PATTERNS = *.py = doxypy：对所有Python文件启用doxypy预过滤，解决动态语法识别错误问题
• 图形渲染基础配置
  • HAVE_DOT = YES：开启dot绘图引擎支持
  • DOT_PATH = 你的本地dot可执行文件路径：如果装完Graphviz没把它加到系统PATH，就手动填dot的全路径，Windows路径注意把反斜杠换成正斜杠
• 调用关系图配置
  • CALL_GRAPH = YES：为每个函数生成正向调用树，展示当前函数调用了哪些其他函数、引用了哪些变量
  • CALLER_GRAPH = YES：为每个函数、变量生成反向调用树，展示当前对象被哪些上层函数调用
  • REFERENCES_RELATION = YES：识别函数内部对外部变量、其他函数的引用关系
  • REFERENCED_BY_RELATION = YES：识别变量、函数被其他位置引用的关系
  • DOT_GRAPH_MAX_NODES = 300：把单张图支持的最大节点数从默认的50调高，避免大项目节点过多被截断
  • MAX_DOT_GRAPH_DEPTH = 0：设置为0代表不限制树形图的展开深度，完整展示多层嵌套调用
  • GRAPHICAL_HIERARCHY = YES：生成类、模块的层级关系树

补全注释解决漏识别问题 #

Python是动态类型语言，静态解析难免有漏判的调用关系，你只需要在对应函数的docstring里用@see标签显式标注关联的函数、变量即可，示例：

# 模块级自定义全局变量
APP_RUNTIME_CONF = {"log_level": "info"}

def format_output(content):
    return f"[RESULT] {content}"

def run_task():
    """
    任务执行入口
    @see format_output
    @see APP_RUNTIME_CONF
    """
    msg = format_output("task done")
    if APP_RUNTIME_CONF["log_level"] == "debug":
        print(msg)

加完标注后Doxygen会100%把对应关联关系挂到树形图中，不会出现缺漏。

常见问题排查 #

• 生成的图缺节点：先确认EXTRACT_ALL已经开启，再检查对应函数、变量是否存在动态赋值导致静态解析无法识别的情况，补@see标注即可
• 控制台提示dot找不到：回去核对DOT_PATH的路径配置是否正确，路径不要包含中文、特殊字符
• 类成员调用关系缺失：确认EXTRACT_PRIVATE已开启，类内部的私有方法、属性默认会被Doxygen过滤

内容的提问来源于stack exchange，提问作者CocowP