PHP 文档生成器的对决:PhpDocumentor2 Vs Sami

PHP 文档生成器的对决:PhpDocumentor2 Vs Sami

Chris Yue No Comment
Posts

您是否也在找一款心仪的 PHP API 文档生成工具?如果是你来对地方了,因为接下来我将请出经典巨星 PhpDocumentor 和新星 Sami 一起上台来做一个对比。

这里单独提一下 Sami,估计很多人都没听说过。这个项目开始于 2012,作者为 Symfony2 项目的主导人 Fabien Potencier,目前 Symfony2 的 API 文档就是由它来生成的。Fabien 也写了一篇介绍性的文章(英文),大家可以看看。

另外本文里的 PhpDocumentor 都指 PhpDocumentor2,功能是在没有扩展的情况下。

功能

 PhpDocumentorSami
可更换主题yes(模板支持twig)yes(模板支持twig)
可扩展yesyes*
错误日志yes 
支持多种格式HTML,PDF 
响应式布局yes 
继承/依赖图谱yes 
支持Markdownyes 
搜索 yes
版本管理 yes(支持git)

注:Sami 的配置文件是 PHP 文件,非常灵活,甚至可以获取到依赖注入服务对象,这样你就可以任意修改他所使用的组件

功能上各有千秋,PhpDocumentor 看上去略胜一筹,不过如何选择还是看个人喜好,比如说我更倾向使用 Sami,就因为可搜索,毕竟自己找还是不如搜索方便啊。

性能

我拿 Symfony2 项目做的测试,文件够多,生成的时间长,会更容易看出差异。
测试机器 Intel® Core™2 Duo CPU T6570 @ 2.10GHz × 2 | 4G DDR2 | Intel SSD

结果(使用 time 命令测试):

 时间
Sami290.09s

而 PhpDocumentor 在执行了55分钟我已经失去耐性的时候被我强行中断了……

然后我用 Symfony 其中一个组件 form 做了测试:

 时间
PhpDocumentaion249.64s
Sami43.79s

可以看到 Sami 速度明显优于 PhpDocumentor,这可能跟 PhpDocument会生成错误报告和依赖/继承图谱,处理 markdown 等任务有关,不过慢得太多也就成了致命伤,而且图谱也是空的……

值得一提的是,Sami 支持增量生成文档。PhpDocumentor 似乎也有某种缓存机制,第二次运行时直接跳过了 parse 阶段,不过结果依然差强人意:

 时间
PhpDocumentaion203.58s
Sami6.94s

这一轮 Sami 以绝对优势胜利

文档

好的项目的一个必备要素就是优秀的文档,可惜 PhpDocumentor 并不具备,有些部分还是空的;但相对于 Sami 来说还是好多了,因为 Sami 就根本没有文档……难道是因为 Fabien 认为 Sami 已经够简单以至于在项目的 README 里面提几句就行了吗……

这个环节上,优胜者是 PhpDocumentor

总结

通过以上的对比,也不能说孰优孰劣,只能说大家按需所取,我个人是倾向于 Sami,除了搜索功能以外,因为 Sami 的配置就是 PHP 文件,所以可以做许多灵活的设置。比如 Sami 指定路径的方式,除了字符串形式的路径外,可以是 Symfony\Finder 返回的迭代器对象,站在强大的的 Symfony\Finder 的肩膀上,你可以非常灵活的设置源文件读取路径。而且还支持通过 git version 生成不同版本的对应的文档,实用性相当高(代码来源):

<?php

use Sami\Sami;
use Sami\Version\GitVersionCollection;
use Symfony\Component\Finder\Finder;

$iterator = Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('Resources')
    ->exclude('Tests')
    ->in($dir = '/path/to/symfony/src')
;

// generate documentation for all v2.0.* tags, the 2.0 branch, and the master one
$versions = GitVersionCollection::create($dir)
    ->addFromTags('v2.0.*')
    ->add('2.0', '2.0 branch')
    ->add('master', 'master branch')
;

return new Sami($iterator, array(
    'theme'                => 'symfony',
    'versions'             => $versions,
    'title'                => 'Symfony2 API',
    'build_dir'            => __DIR__.'/../build/sf2/%version%',
    'cache_dir'            => __DIR__.'/../cache/sf2/%version%',
    'default_opened_level' => 2,
));

另外除了这两款 PHP 制作的文档生成工具以外,还有其他许多工具也是很优秀的,比如 Doxygen
支持多种语言生成文档,而且支持更多的输出格式,也是值得关注的。

PHP 文档生成器的对决:PhpDocumentor2 Vs Sami by Chris Yue is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.

微信赞赏码

写作累,服务器还越来越贵
求分担,祝愿好人一生平安
天使打赏人

发表评论

90 − = 87