幫助文檔生成器(Doxygen)

Doxygen已經(jīng)支持生成ANSI編碼的chm目錄文件（index.hhc）！Doxygen通常是用作生成英文文檔的，生成中文文檔需要修改輸入和輸出的碼制，這樣可以改變解析方式，生成中文文檔。但是，你必須意識 到，Doxygen在從注釋中抽取信息是需要做語法解析的，這些解析都是基于英文的基礎(chǔ)，不可能在這個層面上支持中文。

Doxygen 是一個 C++, C, Java, Objective-C、Python、IDL (CORBA 和 Microsoft flavors)、Fortran、VHDL、PHP、C#和D語言的文檔生成器�？梢赃\行在大多數(shù)類Unix系統(tǒng)，以及Mac OS X操作系統(tǒng)和Microsoft Windows 。 初始版本的Doxygen借鑒了一些老版本DOC++的代碼；隨后，Doxygen源代碼由Dimitri van Heesch重寫。

Doxygen是一個編寫軟件參考文檔的工具。 該文檔是直接寫在代碼中，因此比較容易保持更新。 Doxygen 可以交叉引用文檔和代碼，使文件的讀者可以很容易地引用實際的代碼。Doxygen的開發(fā)作為方便和訪問文件系統(tǒng)的C，C，Java中的Objective-C，Python中，IDL，并在一定程度上的PHP，C＃和D。

更新日志：

Doxygen 1.8.4 改進(jìn)了跨引用、語法高亮和通過 LLVM/clang 解析源碼來獲取調(diào)用圖表的特性，支持 DocBook 輸出和解析 UNO IDL 文件，此外還包含一些小改動和提升以及 bug 修復(fù)。

Doxygen怎么用？

下載和安裝 Doxygen

下載最新的Doxygen安裝程序，然后安裝。這個軟件包包括了一個GUI界面的前端工具，可以幫助我們方便創(chuàng)建Doxygen配置文件和生成目標(biāo)文檔。

下載和安裝 chm 編譯器

我們使用微軟古老的 HTML Help Workshop 1.3，這個軟件N久沒更新了。

下載后根據(jù)提示安裝。

項目一般設(shè)置

首先在“Wizard”標(biāo)簽的Project項進(jìn)行如下設(shè)置：

項目名稱：將在最新的文檔首頁中顯示

源碼列表：選擇要生成文檔的源代碼或目錄，可以有多個文件或目錄形成一個列表。建議使用相對路徑，相對于當(dāng)前目錄（也即當(dāng)前配置文件所在的目錄）

遞歸掃描：如果需要對整個源碼目錄下的所有子目錄及文件生成文檔，請勾選本項

輸出目錄：設(shè)置最終生成的幫助文檔的存儲路徑，建議使用相對路徑

下一步，Mode項，根據(jù)需要設(shè)置文檔生成模式。

下一步，Output項，設(shè)置輸出格式，勾選HTML和“prepare for compressed HTML(.chm)”

然后切換到“Expert”標(biāo)簽的“HTML”項，設(shè)置HTML和CHM相關(guān)的選項：

GENERATE_HTMLHELP：確保已經(jīng)勾選了

CHM_FILE：最終生成的.chm的文件名，如“HkcProjectHelp.chm”。默認(rèn)為“index.chm”。可以使用路徑，也可以使用相對路徑，相對于上面設(shè)置的輸出目錄的html目錄（建設(shè)使用上一級目錄，如“..\MyDoc.chm”）

HHC_LOCATION：chm 編譯器（hhc.exe）的全路徑。請指到 HTML Help Workshop 的安裝目錄的 hhc.exe 程序

CHM_INDEX_ENCODING：chm索引文件編碼，下面會講到，這里填“GBK”

編碼設(shè)置

編碼設(shè)置很重要，如果設(shè)置不當(dāng)，生成的文檔會出現(xiàn)亂碼。因為 Doxygen 汲及的東西多，有好幾項編碼設(shè)置，所以需要認(rèn)真對待，根據(jù)項目的實情情況設(shè)置。

所有高級設(shè)置（包括編碼設(shè)置）都在“Expert”標(biāo)簽，重要的設(shè)置項如下：

Project/DOXYFILE_ENCODING：當(dāng)前 Doxygen 配置文件本身的字符編碼，默認(rèn)為UTF-8，一般不需要修改

Project/OUTPUT_LANGUAGE：輸出語言。這里是指Doxygen自己生成的導(dǎo)航、提示、幫助等文本的文字采用的語言。我們希望幫助文檔是全中文的，所以選擇Chinese

Input/INPUT_ENCODING：輸入文件的編碼。這里是指我們的源代碼文件本身的編碼。在Windows平臺一般是系統(tǒng)編碼（GBK），而Linux平臺一般是UTF-8。請用文本編輯器查看源文件的編碼。這里如果設(shè)置的不一致，源碼文件的注釋中所有非ASCII字符將在生成的文檔中變成亂碼。

HTMP/CHM_INDEX_ENCODING：這里設(shè)置Doxygen生成的CHM索引文件的編碼，以前是不能設(shè)置的，默認(rèn)為UTF-8，而微軟的編譯器不能識別UTF-8編碼的索引文件，所以最終造成左邊目錄導(dǎo)航欄亂碼。我們設(shè)置它為GBK，這樣Doxygen將為我們生成GBK編碼的索引文件（.hhc、.hhk、.hhp）

生成CHM文檔

設(shè)置好了后，點擊“Run”→“Run doxygen”生成最終的.chm文檔，如果設(shè)置正確，打開后是全中文的了。