背景
在查找 ffmpeg 文档的时候,发现其文档是根据 Doxygen 生成的。
为了学习方便,这里以 生成 ffmpeg 4.1 文档 为例。
注:为了兼顾 arm 与 host ,本人选择了同时都支持的 ffmpegv.4.0.1。此后的学习都以此为版本。
Doxygen简介
Doxygen是一个程序的文档产生工具,可以将程序中的注释转换成说明文档或者说是API参考手册,从而减少程序员整理文档的时间。当然这里程序中的注释需要遵循一定的规则书写,才能让Doxygen识别和转化。
目前Doxygen可处理的程序语言包含C/C++、Java、Objective-C、IDL等,可产生出来的文档格式有HTML、XML、LaTeX、RTF等,此外还可衍生出不少其它格式,如HTML可以打包成CHM格式,而LaTeX可以通过一些工具产生出PS或是PDF文档等。
Doxygen 安装及使用
下面以 Windwos 的安装(除了需要设置环境变量以外,无需特别设置)与使用为例
安装列表:
Doxygen: 下载地址,http://doxygen.nl/files/doxygen-1.8.17-setup.exe
HTML Help:微软官方用于生成HTML格式的help文件,下载地址,http://go.microsoft.com/fwlink/p/?linkid=14188
Graphviz:一种dot工具可以用来渲染出效果更好的图表,下载地址,https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi
安装完成以后,将 dot.exe 所在目录(例如:"C:Program Files (x86)Graphviz2.38in")加入系统环境变量中。
基于 Doxygen 的设置
Doxygen 有命令行(CMD tool)工具以及界面化(GUI)工具2种。Windows 下常用 界面 设置。
打开 Doxywizard (Doxygen GUI fronted)
根据实际情况填写以下位置,点击next。
注意,文件路径不要有中文路径,在C盘运行程序的时候,需要有执行权限。
要勾选Scan recursively
Mode 设置模式
在Select the desired extraction mode
:
- 选择
All Entities
- 勾选
Include cross-referenced source code in the ouput
在Select programing languge the optimize the results for :
根据实际项目的需要选择对应的语言
选择:Optimize for C or PHP output
点击next
。
Oputput 设置输出
在Select the output format(s) to generate
- 勾选
HTML
- 选择:
prepare for compressed HTML(.chm)
不勾选 Latex
这里不打算使用 LaTex 工具进行输出 有关文档。
点击next
。
Diagrams 设置图例
在Diagrams to generate
:
选择 Use built-in class diagram generator
勾选Dot graphs to generate
下所有项目
点击next
。
Run doxygen
经过上一步以后,此时应该是跳转到了Expert
选项卡,不理它,选择Run
选项卡。
Expert
选项卡可以实现更加细致的参数设置,一般用在支持中文编码等方面上。
点击 Run doxygen
,经过漫长的编译,生成文件在工程 doc/html/xxx.chm (xx 代表项目名称)
也可以点击 Show HTML output
查看生成的本地文档