楓葉筆記本

/* 2012.7.18 Maple 撰寫 */

phpDocumentor 官方網站：http://www.phpdoc.org/

先不負責任的比較一下兩個版本的差異吧.....

	phpdoc 1.4.4	phpdoc 2.0
需求	php 版本似乎沒限制 pear	PHP 5.3.3 以上 pear iconv extension XSL extension
樣板	html 多種 pdf chm	html 一種
tag 指令	似乎是一樣的	似乎是一樣的
語系 bug	預設語系 iso-8859-1 非此語系會亂碼 ( 可能還有救 )	預設語系 utf8
轉檔指令	些微不同，但不能兩個都裝	指令比 1.4.4 版少

 

若要安裝 1.4 版的，網路上有很多寫得好的文章 (我的參考資料) :

http://pkwbim-programming-note.blogspot.tw/2008/01/phpdocumentor-0.html

http://pkwbim-programming-note.blogspot.tw/2008/01/phpdocumentor-1.html

http://phorum.study-area.org/index.php/topic,48764.msg247116.html

 

以下主要是 phpdoc 2.0 安裝筆記，環境為 win7 系統，apache 2.4 + php 5.3.9

 

首先確定 php 環境是否有 pear

1.若沒有 php/pear 資料夾

檢查是否有 php/go-pear.bat

2.沒有 php/go-pear.bat 的話

請執行原本安裝 PHP 的 php.exe 檔案(如果還有留著的話)

然後選擇修改，加裝 pear 上去

裝好後，應該就會看到 go-pear.bat

(安裝前最好備份一下 httpd.conf  可能會異動到唷)

3.檢查 php/pear 底下資料夾，是否有其他基本的安裝檔案

若只有一個檔案，代表還沒裝

執行 go-pear.bat ，中間就按Y或下一步，一路安裝到底

若出現 PHP_PEAR_PHP_BIN 錯誤，請觀看解決文章

http://www.reai.us/windows-fix-php_pear_php_bin-is-not-set-correctly

其實就是 pear.bat 裡面的 PHP_PEAR_PHP_BIN 的 php.exe 路徑設定不正確 改掉就好了

安裝 phpdoc ，請先檢查環境中 pear.bat 檔案在哪

開啟 cmd ，切換到 pear.bat  的所在目錄，執行以下指令

安裝 phpdocs 1.4 版的指令是
  pear install -o PhpDocumentor

安裝 phpdocs 2.0 版的指令是
  先檢查連的到官方網址 ( 如果我理解沒有錯的話 )
  pear channel-discover pear.phpdoc.org
  執行安裝
  pear install phpdoc/phpDocumentor-alpha

1.安裝過程中要是出現超出記憶體限制或下載失敗，請去修改 php.ini 記憶體及暫存檔案大小的設定

2.移除 phpdocs 就是改使用 pear uninstall 的指令

3.欲安裝 2.0 版，需檢查 PHP 是否有安裝 iconv 及 XSL ，且 php.ini 有載入

   若未安裝，其安裝方式跟加裝 pear 一樣是執行 php 安裝檔案，選擇修改後附加

 

產生文件，用 cmd 執行指令

開啟 cmd ，切換到 phpdoc.bat 的所在目錄，執行指令

若要查詢可用指令，可打 phpdoc -h

1.4 版執行指令

phpdoc -o <樣板> -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY> -i <IGNORE_FILES>

1.4 版指令說明  ( 2.0 版沒有 -o 的屬性 )
http://jax-work-archive.blogspot.tw/2011/12/php-documentor-phpdoc.html

 

我個人比較喜歡 樣板 HTML:frames:earthli ，而 HTML:Smarty:PHP 則跟 PHP 官網風格類似

另外1.4 版預設網頁語系是 iso-8859-1，因此會有亂碼問題

簡單的解決方法 : 可使用 .htaccess 更改編碼 ( 適用於網址瀏覽 HTML 文件亂碼 )

一勞永逸的解決方法：

將PHP安裝目錄 \data\phpDocumentor\phpDocumentor\Converters\ 下的檔案，把模板內容有 iso-8859-1 全部替換成 utf-8

( 若找不到，可能在 php\pear\phpDocumentor 下 )

但是 PDF 的亂碼無解，因為好像是用二進位方式產生 ( 我 try 了好久，搞不定...放棄... )

 

2.0 版執行

phpdoc run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY> -i <IGNORE_FILES>

若執行中出現

DOMDocument::loadXML(): Input is not proper UTF-8, indicate encoding !

請檢查轉出來的檔案 structure.xml ，用 notepad++ 開啟是否中文有出現亂碼

結尾要是為文"章"、增"加"等特定中文字容易會遇到此問題，

解決方式：不要讓這些字當做此行最後結尾字！在後面加上其他的符號，如.或。 即可以解決

2012.7.12 補充

win7 安全性更新後 cmd 執行會一直跳出無法載入 php 檔案的錯誤訊息

Could not open input file: \phpdoc.php

不知道是不是權限被系統鎖住

解決方式：改用自己寫 .bat 檔案，內容寫為

"PHP安裝路徑/php.exe" "PHP安裝路徑/phpdoc.php" -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY> -i <IGNORE_FILES>

存檔後，點兩下執行即可