用于php代码文档的Sphinx

Sphinx是一个Python库,可以从一组ReST格式的文本文件生成很好的文档.不是用于全文搜索的工具

我也完全了解doxygen/phpdoc工具.我想弄清楚是否有办法使用Sphinx来记录php项目？甚至任何其他非python语言？

http://sphinx.pocoo.org/

根据我的经验,Sphinx和ReST可以用作通用文档工具.没有关于Sphinx的任何内容,只允许您将它用于基于Python的项目.例如,在我的工作中,我用它来构建用户指南和XML-RPC API参考.在这两种情况下,我都没有使用sphinx.ext.autodoc或其他特定于Python的附加功能.该文档是"手工"编写的,主要是通用的ReST指令,而不是Sphinx提供的专业指令.对于它的价值,我还不需要为非Python文档创建自定义ReST指令.

即使您正在使用PHP项目,我认为您会发现Sphinx非常有用.例如,模块特定标记提供的大多数指令实际上都非常通用.我不明白为什么你不能或不会使用这些结构来记录Python以外的语言.同样,Sphinx可以很容易地在其他语言中显示代码示例.甚至还有一个配置值可以将默认值更改为Pygments支持的任何语言(包括PHP).如果你感觉特别雄心勃勃,你甚至可以创建一个Sphinx扩展来从你的PHP代码中获取相关内容.

总而言之,请务必考虑您的文档项目的受众.虽然我认为Sphinx是一个很好的工具,并且会推荐它用于各种文档项目,如果您的观众期待别的东西,请注意这一点.例如,如果您正在记录Java项目,那么您的大多数受众可能会期待Javadoc样式的文档.如果你偏离了这种期望,那么确保它不只是为了踢(即,它给你提供比你更好的文档更好的文档)并且准备(简要地)为你所做的事情做出不同的判断(例如,常见问题解答或介绍).

最后,任何文档都比没有文档更好,无论用于创建它们的工具如何.使用任何可以帮助你的工具,如果在那里得到一些东西之间的差别.

刚刚发布的几天前:http: //mark-story.com/posts/view/sphinx-phpdomain-released