JAVA eclipse(myeclipse)生成幫助文檔（html或chm格式）

目錄(?)[+]

轉自：http://www.blogjava.net/lishunli/archive/2010/01/07/308618.html

Javadoc轉換chm幫助文檔的四種方法總結

V1.0

關鍵詞

Javadoc chm 轉換 jd2chm javadoc2chm javadoc2help Javadoc2chm 中文亂碼 李順利

前言

朋友，當您在一個項目完成後，是不是需要把你的源碼打包并且把注釋打成Javadoc交給客戶，Eclipse或者MyEclipse自動打成的Javadoc文檔都是基于網頁格式的，打開是很友善，不過真的用的時候，搜尋每個方法或者什麼的就很麻煩了，而chm幫助文檔格式不但檔案小，查閱都很友善，是以網上就出現了很多把Javadoc轉換為chm格式的幫助文檔的軟體/工具或者方法。

自己最近需要真的需要這個方面的需求，查閱了網上很多方法，發現很多都是寫的很不詳細，對于我這種剛接觸的很是不清楚，經過我的學習和了解，現提供從網上總結的Javadoc轉換chm幫助文檔的四種方法，詳細提供各個轉換的步驟供大家學習，并且提供英文版本和中文版本Javadoc轉換過程中出現的問題，特别是中文的時候出現的亂碼現象，也提供一些解決方案。

預處理

轉換之前需要了解的是chm是微軟公司釋出的一種幫助文檔格式，所有，要使用下面的方法轉換，請先安裝HTML Help Workshop（後面簡稱為HHW）（實際上後面的一些處理有些都是在上面操作的）

http://msdn.microsoft.com/en-us/library/ms669985.aspx，下載下傳完畢後就是安裝了，很簡單。

還有一個很重要的問題，就是如何把項目打成Javadoc，這有人應該會說，很簡單啊，就是使用Eclipse或者Myeclipse的Export功能，是的，這是可以，但是有些小的方面還是需要我們強烈注意的

第一個問題就是Java代碼的格式問題

Java代碼編寫的使用有的使用GBK，有的使用UTF-8，這個時候就會有差別。使用GBK編碼的時候生成Javadoc文檔時沒有太大問題的，但是，要是整個項目的預設編碼格式是UTF-8的話，就會報警告：編碼 GBK 的不可映射字元

根本沒有成功生成Javadoc文檔，如何解決？解決方案就是在生成Javadoc的時候對VM options進行編碼設定-encoding UTF-8 -charset UTF-8，設定如下：

第二個問題就是如何把生成的Javadoc文檔生成英語版本

這個問題有的時候為了解決中文亂碼是很重要的，我們生成英文版本的Javadoc（僅對生成的Javadoc架構的語言做限制，并沒有對注釋内容的格式做限制，也就是說這個時候注釋還是可以是中文的）。

解決方案也是在VM options中加入-locale en_US，但是此時注意的是，如果把-locale en_US設定在後面的話，會報一個錯誤，大緻是-locale en_US在javadoc指令必須是在最前面，所有，正确的寫法就是-locale en_US -encoding UTF-8 -charset UTF-8（整合上面），預設如果不寫-locale的話，安裝locale語言來進行設定，當然我們中國人就是中文的了。（當然如果你工程預設編碼是GBK而且您想生成中文的幫助文檔的話，這寫都可以不要，使用預設即可）

設定截圖如下：

做好了上面的工作，現在就請大家看我是如何轉換成chm幫助文檔的。

（做完這些，請生成中文和英文各一份Javadoc文檔，供後面測試使用）

第一種：使用jd2chm來生成chm幫助文檔

使用原版jd2chm_exe_03轉換成chm

原版jd2chm_exe_03需要通過官網下載下傳http://www.burgaud.com/jd2chm.html不過現在我這是不可以通路的，隻能通過代理來通路下載下傳工具。（不要擔心，最後我會把所有的工具打包供大家下載下傳）。下載下傳解壓後就是一個jd2chm.exe檔案，怎麼使用？很簡單，就是把這個檔案放到需要生成Javadoc的目錄下，必須保證同一個目錄下一定要有index.html，不然不可生成，單擊，或者在cmd指令中打開exe，填寫project name和title即可。

生成英文版本如下

生成中文版本如下

上面整個生成都很OK，中英文支援都非常的好，唯一遺憾的是，工具生成的時候加了About…和沒有順便生成.HHP, .HHK, .HHC檔案，有的時候About我們并不需要或者換成其他的，這個時候可以使用其他的chm編輯器或者HHW反編譯修改後重新編譯生成，具體操作請大家嘗試。

使用網上高手改進的版本jd2chm_0.34轉換成chm

網上一個高手修改了一些很多有用的地方，如果想了解的話，請移步http://download.csdn.net/source/1024968檢視并下載下傳。

生成英文版本如下

請注意最後一個一定要選擇y，意思就是在原Javadoc文檔裡修改一點東西（就我看，就是加了一個about.html），是否同意？不同意如何生成？

生成中文版本如下

比原版本的好處是不需在放到Javadoc目錄下了，還可以使用最新的微軟雅黑字型，而且能夠生成hhc、hhk、hhp檔案，友善我們使用HHW進行編輯。遺憾還是about并且有點破壞了原Javadoc文檔（加了一個about.html），這個時候通過HHW工具很友善的進行編輯（有了hhc、hhk、hhp檔案）。修改一份給大家看看，打開hhp檔案，并打開About…檔案，修改部分内容（就是一個html語言寫的網頁了）

修改完成後，儲存并編譯

對比下面修改後的About

第二種：使用javadoc2chm來生成chm幫助文檔

先下載下傳工具javadoc2chm-1.1.0.7.msi，搜尋下載下傳（後面會提供），下載下傳完成并安裝，會在開始菜單裡生成程式快捷方式。

生成英文版本如下

生成中文版本如下

界面操作，很友善，英文支援非常好，中文有一處亂碼（上面目錄第一層），幾乎很完美，遺憾是Title後面加了-Generated by javadoc2chm和中文有點亂碼，沒有生成hhc、hhk、hhp檔案(實際上在轉換的時候是生成的這三個檔案，後面被删除了，如果耍點小聰明的話，可以在生成過程中複制一份，如果速度快的話，會提示檔案已經被删除，是否重試，這個時候再轉換，看檔案生成後點重試即可得到這三個檔案，不要反編譯多好)，這種方法建議使用英文版本。

自己修改了一份中文版本的轉換，現提供部分步驟

看看修改後的效果吧

第一次打開的首頁

個性化設定：加入Blog，請大家有空多踩踩我的部落格：http://blog.sina.com.cn/usc3l

上面的兩種方法也是我極力推薦大家使用的，下面的兩種方法僅供學習，裡面有很多問題，中文亂碼什麼的，都會出現。

第三種：使用javadoc2help來生成chm幫助文檔

官方網站http://javadoc2help.sourceforge.net/，下載下傳解壓即可，裡面最重要的就是lib目錄下面的Javadoc2Help.jar，注意我們就是使用這個jar檔案進行生成。官網上也提供了如何使用。

生成英文版本如下

Cmd指令進入jar檔案目錄，寫下面的指令回車

java -jar Javadoc2Help.jar -chm -src f:/docs/api_en_US -dest f:/docs/api_en_US2

（具體路徑請根據需要修改）

注意：-dest後面的目錄請不要寫原目錄，不然生成不了chm并且覆寫了原目錄檔案。

生成中文版本如下

Cmd指令進入jar檔案目錄，寫下面的指令回車

java -jar Javadoc2Help.jar -chm -src f:/docs/api_zh_CN -dest f:/docs/api_zh_CN2

（具體路徑請根據需要修改）

注意：-dest後面的目錄請不要寫原目錄，不然生成不了chm并且覆寫了原目錄檔案。

基本能夠完成轉換，但是不了建立索引，不能設定Title和檔案名，對中文嚴重不支援不管是英文版本還是中文版本的chm都出現了中文亂碼現象，還有chm檔案就是便于查詢，竟然不能生産索引，建議不使用。

第四種：使用google code裡面的javadoc2chm項目建構

請參考http://code.google.com/p/javadoc2chm/下載下傳ruby和javadoc2chm-0.1.zip等必要步驟。

Google code上頁介紹了如何使用，解壓壓縮包。使用這個，就必須先安裝ruby和HHW。

生成英文版本如下

Cmd指令進入javadoc2chm目錄，寫下面的指令

ruby createhhp.rb api_en_US f:/docs/api_en_US回車

"C:/Program Files/HTML Help Workshop/hhc.exe" api_en_US.hhp回車

（注意C:/Program Files/HTML Help Workshop/hhc.exe是HHW預設安裝路徑，如果不是請自行修改）

生成的chm檔案在解壓的包的檔案夾裡：

打開後是上面的這樣子，具體的原因不清楚，不過解決的方法就是把Javadoc檔案夾和ruby指令的檔案夾不要放在同一個盤内，不在同一個盤裡就會使用絕對路徑。重修生成，但是這種方法也并不适合，當我們把原Javadoc文檔的檔案夾删除或者移動了，這個時候也會出現上面的情況。具體的我打開了hhp檔案檢視了一下，應該是這種方法使用的是覺得路徑，而并沒有把檔案進行包裝在生成。（要檢視下面截圖的效果，請把docs檔案夾保留）

指令

ruby createhhp.rb api_en_US e:/docs/api_en_US

"C:/Program Files/HTML Help Workshop/hhc.exe" api_en_US.hhp

生成中文版本如下

Cmd指令進入javadoc2chm目錄，寫下面的指令

ruby createhhp.rb 中文幫助文檔 e:/docs/api_zh_CN回車

"C:/Program Files/HTML Help Workshop/hhc.exe" 中文幫助文檔.hhp回車

（注意C:/Program Files/HTML Help Workshop/hhc.exe是HHW預設安裝路徑，如果不是請自行修改）

不能設定Title和中文的Title時候亂碼，操作麻煩，還要安裝ruby輔助軟體。

總結

上面的一些不完美的地方，都可以使用HTML Help Workshop進行改善。實際上也是因為此次機遇，讓我學習了HTML Help Workshop的操作，以後制作chm文檔就很友善了。

上面方法通過參考網上的操作總結自己親自實際而成，需要探讨的請聯系QQ：506817493。

順利提高所有工具和制作成果的檔案下載下傳(不包括ruby輔助軟體，自行下載下傳)

Javadoc轉換chm幫助文檔的四種方法總結.rar