doxygen 中文文档生成和 latex 设置

Table of Contents

一直使用 doxygen 生成 C 程序库的文档,还是相对简单的,只要按照它的注释格式给每个符号写注释就可以。 有一个人忽然说要中文的PDF文档,别的格式还不行,确实折腾了一番。主要是因为 latex 的中文支持我到现在都没明白。 这里把整个支持的过程记录下来,希望能对有相同需求的朋友提供帮助。

在 github 上写了个简单的例子,演示如何完成整个过程。

1 生成并编辑 Doxyfile 配置文件

代码和注释都完成后,在项目目录使用下列命令生成 doxygen 的初始配置:

doxygen -g

初始文件在当前目录, 名为 Doxyfile。打开后按需修改一些变量:

# 项目名称, 将显示为标题
PROJECT_NAME           = "simple_gmsm"
# 文档生成目录
OUTPUT_DIRECTORY       = target/doc
# 输出语言
OUTPUT_LANGUAGE        = Chinese
# 扫描哪些文件
INPUT                  = include/ .
# 递归扫描
RECURSIVE              = YES
# 忽略哪些文件
EXCLUDE_PATTERNS       = */doxy/* */target/*
# 文档主页使用 READMD.md
USE_MDFILE_AS_MAINPAGE = README.md
# 使用 mathjax 显示公式
USE_MATHJAX            = YES

# 为了使用系统安装的字体, 我选择 xelatex
LATEX_CMD_NAME         = xelatex
# 生成的 latex 一些设置我不喜欢, 使用自定义的 header 和 footer
LATEX_HEADER           = doxy/header.tex
LATEX_FOOTER           = doxy/footer.tex
LATEX_EXTRA_STYLESHEET = doxy/doxygen.sty

# html 的 header, footer 内容我们也经常修改
HTML_HEADER            = doxy/header.html
HTML_FOOTER            = doxy/footer.html
HTML_STYLESHEET        = doxy/stylesheet.css

# 输出位置,我希望输出到 target/doc 目录下
OUTPUT_DIRECTORY       = target/doc

2 生成并编辑 header, footer

doxygen 的文档结构挺复杂的,要自己写 header 和 footer 不一定能写对。 使用下列命令生成默认的。

# 生成 latex 的 footer 和 header
doxygen -w latex doxy/header.tex doxy/footer.tex doxy/doxygen.sty
# 生成 html 的 footer 和 header
doxygen -w html doxy/header.html doxy/footer.html doxy/stylesheet.css

html 格式的 footer 和 header 按照喜好修改就可以了,不难。 latex 格式的 header 因为要支持中文,需要特别注意。

我希望使用系统的字体,所以使用 xelatex, 而不是 CJK ,字体我使用 AR PL Sungtil GB 也就是文鼎简报宋。 所以在 header.tex 注释掉 \usepackage{CJKutf8}\begin{CJK}{UTF8}{min} 。并设置使用xeCJK \usepackage{xeCJK} , 设置主字体 \setCJKmainfont{AR PL SungtiL GB}

字体名称可以通过 fc-list 查看。

在 footer.tex 中注释掉 \end{CJK}

再作其它修改,例如修改 title 等。需要注意的是 latex 格式里,下划线是需要转义的。

As you can see

3 生成文档

生成之前需要安装 doxygen, 合适的字体,以及 xelatex。因为我也不知道怎么最小化安装 latex,所以选用 texlive-full。

# 生成 html 和 latex 源文件
doxygen 
# 编译 latex 文件生成 pdf
cd target/doc/latex
make

随后 refman.pdf 就是生成的 PDF 中文文档。

4 其它设置

我发现一个 doxygen-awesome-css 项目可以把生成的 html 文档设置为更好看的样式,可以尝试一下。


By .