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 格式里，下划线是需要转义的。
3 生成文档
生成之前需要安装 doxygen, 合适的字体，以及 xelatex。因为我也不知道怎么最小化安装 latex，所以选用 texlive-full。
# 生成 html 和 latex 源文件 doxygen # 编译 latex 文件生成 pdf cd target/doc/latex make
随后 refman.pdf 就是生成的 PDF 中文文档。
4 其它设置
我发现一个 doxygen-awesome-css 项目可以把生成的 html 文档设置为更好看的样式，可以尝试一下。