PHP DocBlox入门
DocBlox是新的事实上的PHP类文档生成器。它被开发为PHPDocumentor的替代产品,但看起来它将替代它并成为新的PHPDocumentor2。结果,我想我会整理一个快速入门指南。
这篇文章假定您知道什么是PHPDoc注释,并且您有一个要为其生成API文档的项目。要开始使用PHPDoc,请查看PHPDoc上的Wikipedia页面。
PHPDocumentor将一次性扫描并生成所有代码,而DocBlox将扫描源代码并根据找到的代码生成一系列XML文件。然后,尽管HTML可能是最常见的格式,它将使用这些文件以多种不同的格式生成API文档。
在使用DocBlox进行任何操作之前,首先应确保已安装以下软件包:
PHP-XSL-这是将XML文件转换成不同格式所必需的。
Graphviz-DocBlox可以另外创建一个继承图,该继承图使用Graphviz包。
PEAR-PHP扩展和应用程序存储库,用于打包和安装DocBlox本身。
所有这些软件包都可以通过Linux上的apt-get甚至Ubuntu上的Synaptic软件包管理器轻松安装。Windows用户将必须手动安装每个组件,但是仍然可以执行。
安装
要安装DocBlox,请运行以下PEAR命令。
pear channel-discover pear.docblox-project.org pear install DocBlox/DocBlox
现在,您可以通过运行docblox命令查看它是否已安装。您应该会在屏幕上看到一条帮助消息。要注意的一件事是,如果Docblox出现错误,它将始终打印出帮助消息,但是该错误将在帮助输出之前首先被打印出来。当我使用一个小的终端窗口来运行命令时,这吸引了我。
用法
DocBlox的默认操作是扫描代码并生成一堆XML文件,其中包含在其中找到的PHPDoc元素的输出。这些文件还将包含用于创建类层次结构图的所有引用数据,例如类祖先。Docblox带有两个默认标志,-d是包含您的代码的目录,-t是输出目录。以下内容将解析当前目录中找到的所有代码,并将输出写入名为output的目录中。如果Docblox无权访问此目录,则会出错,因此最好在开始之前创建它并设置权限。
docblox -d . -t output
您可以通过执行以下操作来解析单个文件,尽管由于未完全生成类祖先,所以这样做的用处不大。
docblox -fFile.php-t output
生成XML文件后,除非文件已更改,否则DocBlox将不需要重新生成它们。这意味着docblox命令的任何后续运行都将更快,因为已经生成了XML文件。
模板
现在我们有了XML文件,我们可以生成HTML文档。这要求我们安装了HTML模板。要查看系统上可用的模板,请运行以下命令。
docblox template:list
对于全新安装,将有一个名为new_black的主题,仅此而已。如果要安装新模板,则可以从DocBlox模板页面中获取一个模板。运行以下命令以从模板页面获取模板名称来安装新模板。
sudodocbloxtemplate:install
现在您可以为该项目生成HTML文档了。您可以通过运行以下命令并添加--template标志来实现。
docblox--template
配置为XML
在本文中,我仅概述了一些命令行选项,但还有更多可用选项。也可以将这些配置选项嵌入XML文件中。如果您创建一个名为docblox.dist.xml的文件并将其放入您的项目目录,则Docblox将自动选择并使用该文件。
以下是Docblox的默认配置文件。这是使事物运行与上述命令相似的结果所需的最少信息量。
data/output data/output .
您可以使用-c或--configuration标志来选择配置文件。
更多信息
这只是对Docblox的初步(也是基本的)了解,因为还有很多要研究的内容。如果您有兴趣,可以在Docblox站点,Docblox文档和Docblox模板站点上找到更多信息。