Clever Geek Handbook

Docblox-PHP 5.3以降と互換性のあるドキュメントシステム

次回PEARを使用してPhingを更新したときに、追加の依存関係のリストに気づき、名前から何もわからないプロジェクトのサイトにアクセスすることにしました。 とりわけ、私はあなたと共有したい1つの有望なプロジェクトを見つけました。 Docblox-有名なPHP Documentorに組み込まれたアイデアを開発するPHPアプリケーションを文書化するための新しいシステムを紹介します。 現時点では、PEAR表記法によると、プロジェクトはベータテスト中ですが、 Zend Framework 、 Phing 、 Fuelなどのプロジェクトの開発で既に使用されています。



PHP Documentorと比較した新機能：

  1. 名前空間のサポート
  2. いくつかの新しい@タグ： api 、 magic 、@ property-read、@ property-write、@ throws
  3. 子クラスのメソッドの説明を継承する機能（空のdocblockを追加すると、親クラスの\インターフェイスから説明がコピーされます）
  4. wikiマークダウン（マークダウンを含む）のような単純なテキスト形式のサポート
  5. 変更されたファイルの追跡（変更されたファイルのみが表示されるため、処理が高速化されます）
  6. 中間XMLファイルによる2段階のドキュメント生成。これに基づいて、HTMLページを生成できます。 XMLファイルのコンテンツには、ソースコードから抽出されたすべての情報が含まれており、プログラマーの裁量で使用できます。
  7. Phingのbuild.xmlに似た構成のXMLファイルのサポート。パラメーターなしでdocbloxコマンドを実行することでドキュメントを生成できます。
  8. テーマとコンテンツ表示テンプレートのサポート
  9. カスタムクラスを追加してXMLデータを任意の形式のファイルにエクスポートする機能
  10. PDFを生成する機能（ WebKitを使用してHTML→PDFを変換するために作成された追加のwkhtmltopdfライブラリが必要）
  11. クラスごとにUMLのようなグラフを生成する機能（Graphvizが必要）

インストール：



プロジェクトには独自のPEARチャネルがあるため、インストールは基本的に簡単です。 

# pear channel-discover pear.docblox-project.org # pear channel-discover pear.michelf.com # pear install DocBlox/DocBlox-beta (-beta   ,  beta-     )


ドキュメントの生成： 



 $ docblox run


docblox.dist.xmlまたはdocblox.xmlファイルが含まれている場合、ソースフォルダーで実行されます。 そうでない場合、エラーがスローされます。 



 $ docblox run --config /path/to/docblox.xml


構成ファイルが現在のディレクトリにない場合。 



 $ docblox run --filename /path/to/file1,/path/to/file2


個々のファイルをリストする必要がある場合。 



 $ docblox run --directory /path/to/src1,/path/to/src2 --target /path/where/to/save/docs


ソースコードを含むファイルの検索ディレクトリと、完成したドキュメントが書き込まれるディレクトリを明示的に指定できます。 参照されるディレクトリはすべて存在する必要があります。 



 $ docblox run --help


ヘルプを呼び出して、Docbloxの他のオプションを見ることができます。



docblox.dist.xmlまたはdocblox.xml構成ファイルの例： 



 <?xml version="1.0" encoding="UTF-8" ?> <docblox> <!-- 1)  \    (  *  ?) --> <files> <directory>src</directory> <directory>tes??</directory> <file>test.php</file> <file>bin/*</file> <ignore>test/*</ignore> </files> <!-- 2) ,     --> <parser> <!-- 2.1)    XML- --> <target>src/docs/xml</target> <!-- 2.2)     @package     --> <default-package-name>core</default-package-name> <!-- 2.3)     ,  ,   --> <markers> <item>TODO</item> <item>FIXME</item> </markers> <!-- 2.4)        --> <extensions> <extension>php</extension> <extension>php3</extension> <extension>phtml</extension> </extensions> </parser> <!-- 3) ,     XML-     --> <transformer> <!-- 3.1)     --> <target>src/docs/html</target> <!-- 3.2)          Std_Class--> <external-class-documentation> <prefix>Std_Class</prefix> <uri>http://external-project.org/docs/latest/</uri> </external-class-documentation> </transformer> <!-- 4)        --> <transformations> <template name="Crystal-Blue" /> </transformations> <!-- 5)    --> <logging> <!-- 5.1)    (   ,    PHP) --> <level>warn</level> <!-- 5.2)     (default)      (errors).  {APP_ROOT}      , {DATE} —    --> <paths> <default>{APP_ROOT}/data/log/{DATE}.log</default> <errors>{APP_ROOT}/data/log/{DATE}.errors.log</errors> </paths> </logging> </docblox>


参照：

現時点では、Docbloxの最新バージョンは0.13.3で、2011年8月末にリリースされています。サイトからのメッセージから判断すると、バージョン0.14はリリースの準備中です。


More articles:


All Articles