2018年6月15日星期五

NetBeans 製作 PHP 說明文件

開發同時兼顧編寫清楚的說明文件,並不容易,甚至製作範例更加麻煩
Java 的 JDK 開發工具提供 javadoc 這種可以直接將源始碼上的特定備註語法轉換成 HTML 說明文件,既方便又快捷
那 PHP 有冇類似的工具能方便製作說明文件?

PHP 有一些第三方工具能協助 PHP 專案製作說明文件,例如: ApiGen, PHPDocumentor
ApiGenPHPDocumentor 都能支援 NetBeans
ApiGen 可以在 apt-get 等系統管理工具上獲得
PHPDocumentor 則需要通過 PEAR 安裝或自行到官方網頁下載及設定
兩者使用上都非常相似,但在下覺得由 ApiGen 製作的說明文件閱讀上方便點,所以主要介紹 ApiGen

見下文
先在 NetBeans 安裝 PHP 及 ApiGen 等外掛程式

見下文
在需要製作文件的 PHP 專案展開選單,點選 Generate Documentation 項目

見下文
雖然 NetBeans 已經安裝 ApiGen 外掛,但仍然需要系統中有 ApiGen 的執行程式

見下文
在 Terminal 輸入
sudo apt-get install php-apigen
安裝 ApiGen

見下文
到 Tools > Options > PHP > Framework & Tools
若按下之前 NetBeans 出現未設定 ApiGen 的錯誤,會自動跳至設定頁面
按下 ApiGen ScriptBrowse 按鈕

見下文
安裝後 ApiGen 的執行程式放在 /usr/bin/apigen

見下文
亦可以在文字欄位中直接輸入 ApiGen 的執行路徑

見下文
設定專案的文件輸出目錄

見下文
建立文件輸出目錄

見下文
選擇文件輸出位置

見下文
確定文件輸出位置

見下文
ApiGen 需要 PHP 的執行程式才能執行

見下文
在 Terminal 輸入
sudo apt-get install php
安裝 PHP

見下文
到 Tools > Options > PHP > Framework & General
若按下之前 NetBeans 出現未設定 PHP 的錯誤,會自動跳至設定頁面
按下 PHP * InterpreterBrowse 按鈕

見下文
安裝後 PHP 的執行程式放在 /usr/bin/php

見下文
同樣,亦可以在文字欄位中直接輸入 PHP 的執行路徑

見下文
再次在 PHP 專案展開選單,點選 Generate Documentation 項目
但發現錯誤,並建議在指令加上 --debug 除錯

見下文
到專案的目錄,執行剛才的指令並加上 --debug
出現 /usr/share/php/FSHL/autoload.php 找不到 /usr/share/php/FSHL/FSHL-2.1.0/FSHL/Lexer/Php.php 的錯誤

見下文
/usr/share/php/FSHL/usr/share/php/FSHL/Lexer 的檔案結構
/usr/share/php/FSHL/FSHL-2.1.0/FSHL/Lexer/Php.php 相似

見下文
因此查看 /usr/share/php/FSHL/autoload.php 內容
發現 /usr/share/php/FSHL/autoload.php 的類別的路徑稍有不同,因此進行修改
function($class) 中加入 $fshl_dir = '' 的路徑
然後將所有 '/FSHL-2.1.0/FSHL 取代成 $fshl_dir . '
其實可以直接將所以 /FSHL-2.1.0/FSHL 刪除即可,但在下認為以 變數 保存可以方便日後再次修改

見下文
完成後儲存檔案
(不一定使用 vim ,用任何閣下方便的文字編輯文件便可以)

見下文
執行指令,出現 Call to undefined function ApiGen\Charset\Configuration\mb_list_encodings() 錯誤

見下文
在 Terminal 輸入
sudo apt-get install php-mbstring
安裝 PHP 的 mbstring 函式庫

見下文
執行指令,能運行到部分,但出現 call to undefined function Latte\Runtime\utf8_decode() 錯誤

見下文
在 Terminal 輸入
sudo apt-get install php-xml
安裝 PHP 的 xml 函式庫

見下文
再次執行指令終於沒有錯誤

見下文
再到 PHP 專案展開選單,點選 Generate Documentation 項目
終於能在 NetBeans 中正常運作

見下文
建立的 PHP 文件的樣式類似由 javadoc 建立的 Java 文件

見下文
在 PHP 專案展開選單,點選 Properties 項目

見下文
Documentation 選項,還有其他設定
有需要可以調整文件輸出的項目

如果閣下架設典型的 LAMP ,在安裝時已經會將 php-xmlphp-mbstring 安裝,只需要再安裝 php-apigen 便完成
如果 PHP, ApiGen 執行程式比 NetBeans 的 PHP, ApiGen 外掛程式先安裝,NetBeans 在安裝外掛後會自動尋找對應的執行程式

沒有留言 :

發佈留言