PHP Documentorと比較した新機能:
- 名前空間のサポート
- いくつかの新しい@タグ: api 、 magic 、@ property-read、@ property-write、@ throws
- 子クラスのメソッドの説明を継承する機能(空のdocblockを追加すると、親クラスの\インターフェイスから説明がコピーされます)
- wikiマークダウン(マークダウンを含む)のような単純なテキスト形式のサポート
- 変更されたファイルの追跡(変更されたファイルのみが表示されるため、処理が高速化されます)
- 中間XMLファイルによる2段階のドキュメント生成。これに基づいて、HTMLページを生成できます。 XMLファイルのコンテンツには、ソースコードから抽出されたすべての情報が含まれており、プログラマーの裁量で使用できます。
- Phingのbuild.xmlに似た構成のXMLファイルのサポート。パラメーターなしでdocbloxコマンドを実行することでドキュメントを生成できます。
- テーマとコンテンツ表示テンプレートのサポート
- カスタムクラスを追加してXMLデータを任意の形式のファイルにエクスポートする機能
- PDFを生成する機能( WebKitを使用してHTML→PDFを変換するために作成された追加のwkhtmltopdfライブラリが必要)
- クラスごとに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>
参照:
- http://www.docblox-project.org/-プロジェクトサイト
- http://demo.docblox-project.org/-生成されたドキュメントの例(各フォルダーはドキュメントプレゼンテーションの異なる外観を使用します)
- http://github.com/mvriel/docblox-GitHubのリポジトリ
- http://twitter.com/docblox-Twitterのマイクロブログプロジェクト