使用Doxygen生成全中文的chm、pdf帮助文档的方法

下载和安装 doxygen

到 doxygen 官网 下载最新的doxygen安装程序，然后安装。这个软件包包括了一个gui界面的前端工具，可以帮助我们方便创建doxygen配置文件和生成目标文档。

下载和安装 chm 编译器

我们使用微软古老的 html help workshop 1.3，这个软件n久没更新了。

下载地址：

下载后根据提示安装。

项目一般设置

首先在“wizard”标签的project项进行如下设置：

项目名称：将在最新的文档首页中显示
源码列表：选择要生成文档的源代码或目录，可以有多个文件或目录形成一个列表。建议使用相对路径，相对于当前目录（也即当前配置文件所在的目录）
递归扫描：如果需要对整个源码目录下的所有子目录及文件生成文档，请勾选本项
输出目录：设置最终生成的帮助文档的存储路径，建议使用相对路径

下一步，
mode项，根据需要设置文档生成模式。

下一步，output项，设置输出格式，
勾选html和“prepare for compressed html(.chm)”

然后切换到“expert”标签的“html”项，设置html和chm相关的选项：

generate_htmlhelp：确保已经勾选了
chm_file：最终生成的.chm的文件名，如“hkcprojecthelp.chm”。默认为“index.chm”。可以使用路径，也可以使用相对路径，相对于上面设置的输出目录的html目录（建设使用上一级目录，如“..\mydoc.chm”）
**hhc_location：**chm 编译器（hhc.exe）的全路径。请指到 html help workshop 的安装目录的 hhc.exe 程序
**chm_index_encoding：**chm索引文件编码，下面会讲到，这里填“gbk”

编码设置
编码设置很重要，如果设置不当，生成的文档会出现乱码。因为 doxygen 汲及的东西多，有好几项编码设置，所以需要认真对待，根据项目的实情情况设置。

所有高级设置（包括编码设置）都在“expert”标签，重要的设置项如下：

project/doxyfile_encoding：当前 doxygen 配置文件本身的字符编码，默认为utf-8，一般不需要修改
project/output_language：输出语言。这里是指doxygen自己生成的导航、提示、帮助等文本的文字采用的语言。我们希望帮助文档是全中文的，所以选择chinese
input/input_encoding：输入文件的编码。这里是指我们的源代码文件本身的编码。在windows平台一般是系统编码（gbk），而linux平台一般是utf-8。请用文本编辑器查看源文件的编码。这里如果设置的不一致，源码文件的注释中所有非ascii字符将在生成的文档中变成乱码。
htmp/chm_index_encoding：这里设置doxygen生成的chm索引文件的编码，以前是不能设置的，默认为utf-8，而微软的编译器不能识别utf-8编码的索引文件，所以最终造成左边目录导航栏乱码。我们设置它为gbk，这样doxygen将为我们生成gbk编码的索引文件（.hhc、.hhk、.hhp）

生成chm文档

设置好了后，点击“run”→“run doxygen”生成最终的.chm文档，如果设置正确，打开后是全中文的了。 

使用doxygen生成中文pdf文档

作者：zyl910

　　众所周知，能够利用doxygen生成pdf文档——但是，如果其中含有中文的话，那就会遇到一大堆问题无法顺利输出。我花了很长时间摸索，最终找到了让doxygen顺利生成中文pdf的办法。

　　系统环境——
1) mac os x lion 10.7.5 + mactex-2012 。
2) windows xp sp3 + ctex 2.9.2.164 。

一、原理解释
　　doxygen本身并不能直接输出pdf文件，而是生成了latex目录，其中有一个 makefile 文件。若系统中装好了pdflatex，可在latex目录中运行“make”命令来生成pdf文件。
　　怎样才能装好pdflatex呢？mac平台可安装mactex，windows平台可安装ctex。

　　环境装好之后，当在latex目录中运行“make”命令来生成pdf文件时会发现——纯英文文档能顺利生成pdf；而含有中文时，不能顺利生成pdf文件。

　　对于latex排版，doxygen其实已经做了很多准备，比如——源文件是utf-8编码，并默认使用了utf8 package。理论上是支持多国语言的。
　　可对于中文来说，还需要加载 cjkutf8 package，并配置好cjk环境。这才能顺利的使用中文。

二、解决方案
　　具体步骤——
1) 使用docxygen生成文档，注意选上 generate_latex 、latex_output、use_pdflatex（最好还选上 pdf_hyperlinks）；

2) 用文本编辑器打开docxygen生成的latex目录中的refman.tex。找到“\begin{document}”这一行，将其修改为——

然后再找到“\end{document}”这一行，将其修改为——

 

保存，关闭。

3) 打开终端，使用cd命令进入latex目录，然后执行“make”命令。执行完毕后后，该目录中会出现“refman.pdf”——

我在 mac + mactex 环境下make时，能完美生成带书签的pdf。
　　而在 win + ctex 环境下make时，其中还会弹出一堆错误（输入r再回车，可忽略后续错误），但是最终还是能够生成中文的pdf，可惜一般不能顺利的构造好书签。