AFSim_二次开发_wsf框架开发文档生成-夜雨聆风

AFSim_二次开发_wsf框架开发文档生成

wsf框架开发文档生成

说明

通常我们在用C++而不是脚本开发时需要查阅一些类的函数和说明，而AFSim的核心框架wsf的API文档的指南需要通过CMake来生成，但发现默认生成的html的类继承关系有问题，经过排查和解决，特形成此文以作分享。本文最后附带了在线查阅链接。

生成步骤

需要准备的工具：

Python（用于安装Sphinx全文检索引擎及转换dot文件到png）

Doxygen（生成API文档）

Graphviz（生成类图的工具）

1）配置CMake

打开AFSim的CMake项目，勾选Doxygen，点击Configure后，其中有两处需要通过安装外部工具后自动获取，如下图：

2）安装Sphinx

首先安装python，我这里安装的是3.12.7，其他版本也可以。通过python安装Sphinx工具，命令为：

安装完成后，点击CMake的Configure，Sphinx已经自动获取到了：

3）安装Doxygen和Graphviz

从网上下载doxygen安装包，双击安装即可。我安装的版本是：doxygen-1.13.0-setup.exe

从网上下载Graphviz安装包，双击安装即可。我安装的版本是：graphviz-install-12.2.1-win64.exe，注意的是需要勾选添加Graphviz目录到Path：

同样，安装完成后，点击CMake的Configure，doxygen已经自动获取:

4）生成

点击CMake的Generate来生成VS解决方案，生成完成后，打开解决方案（如果之前已经生成过，这里只需要点击全部重新加载即可）。打开后，点击批生成，勾选ALL_BUILD（也可以只选择Doxygen）和INSTALL后，点击生成：

生成完成后，在输出目录中的doxygen/html文件夹就是最终生成的WSF框架的API文档。打开html文件夹中的index.html文件，如下图：

搜索WsfPlatform类，并打开如下图：

这里发现，继承图（inheritance）和协作图（collaboration）并没有显示出来，跟踪后发现，它是引用了png文件，但目录下不存在png，只有同名的dot文件：

查询资料了解到png文件是通过Graphviz的dot.exe工具来将dot文件转换为png文件。（我这CMake是配置了dot.exe的路径的，但生成时并没有起作用，原因未知。只能自己将dot转换为png了）

5）转换dot到png

在生成的doxygen/html文件夹及子文件夹中有很多的dot文件，此dot文件可以通过Graphviz的dot.exe工具来转换为png文件，并保存到同样的目录下，在API文档的html页面中就能看到了，如下：

dot转换png的指令：dot.exe -Tpng xxx.dot -o xxx.png，由于需要遍历所有目录下的dot文件，因此这里我通过构建python脚本来遍历所有dot文件，并调用指令来转换：

import osimport subprocessdef convert_dot_to_png(root_dir):    """将指定目录及其子目录下的所有.dot文件转换为.png文件"""    for root, dirs, filesinos.walk(root_dir):        for filename in files:            if filename.endswith(".dot"):                # 构建完整文件路径                dot_path = os.path.join(root, filename)                # 生成对应的png文件名                png_filename = os.path.splitext(filename)[0] + ".png"                png_path = os.path.join(root, png_filename)                try:                    # 执行转换命令                    subprocess.run(                        ["dot", "-Tpng", dot_path, "-o", png_path],                        check = True                    )                    print(f"成功转换：{dot_path} -> {png_path}")                except subprocess.CalledProcessError as e:                    print(f"转换失败：{dot_path}。错误码：{e.returncode}")                except FileNotFoundError:                    print("错误：找不到dot命令，请确保Graphviz已安装并添加到系统路径")                    return                except Exception as e:                    print(f"处理 {dot_path} 时发生未知错误：{str(e)}")if __name__ == "__main__":    import sys    target_dir = "E:/AFSim2.9/doxygen/html"    if not os.path.isdir(target_dir):        print(f"错误：{target_dir} 不是有效目录")        sys.exit(1)    convert_dot_to_png(target_dir)