Sphinx为php代码文档 [英] Sphinx for php code documentation
问题描述
Sphinx是一个Python库，用于从一组ReST格式的文本文件生成不错的文档。不是用于全文搜索的工具
Sphinx is a Python library to generate nice documentation from a set of ReST formatted text files. Not the tool used for full-text searching
我还完全了解doxygen / phpdoc工具。我想弄清楚是否有一种使用Sphinx来记录php项目的方法？甚至任何其他非蟒蛇语言？
I'm also fully aware of doxygen / phpdoc tools. I'm trying to figure out if there is a way of using Sphinx to document php projects? or even any other non-python languages?
推荐答案
根据我的经验，Sphinx和ReST可以用作通用文档工具。没有什么关于Sphinx，它只允许您使用它为基于Python的项目。例如，在我的工作中，我已经用它来构建用户指南和XML-RPC API参考。在这两种情况下，我没有使用 sphinx.ext.autodoc 或其他特定于Python的附加功能。这些文档是用手工编写的，大部分是通用的ReST指令，而不是由Sphinx提供的专业指令。对于什么是值得的，我还没有需要为非Python文档创建自定义的ReST指令。
Sphinx and ReST can be used as generic documentation tools, in my experience. There's nothing about Sphinx which obligates you to only use it for Python-based projects. For example, in my work, I've used it to build a user guide and an XML-RPC API reference. In both cases, I had no use for sphinx.ext.autodoc or other Python-specific extras. The documentation was written "by hand," with mostly generic ReST directives, rather than the specialty directives provided by Sphinx. For what it's worth, I have not yet needed to create a custom ReST directive for non-Python documentation.
即使你正在使用PHP项目，我认为你会发现Sphinx有用。例如模块特定标记提供的大多数指令是其实很普遍。我不明白为什么你不能或不会使用这些结构来记录Python以外的语言的东西。同样，Sphinx可以很容易地显示其他代码示例语言的。甚至有一个配置值将默认值更改为Pygments支持的任何语言（包括PHP）。如果您感觉特别雄心勃勃，您甚至可以创建狮身人面像扩展名，以从您的PHP代码。
Even if you're working with a PHP project, I think you'll find Sphinx useful. For example most of the directives provided by the module specific markup are actually quite general. I don't see why you couldn't or wouldn't use these constructs to document stuff from languages other than Python. Likewise, Sphinx makes it pretty easy to show code examples in other languages. There's even a configuration value to change the default to any language which Pygments supports (which includes PHP). If you're feeling particularly ambitious, you could even create a Sphinx extension to pluck something relevant from your PHP code.
所有这一切，请务必考虑您的文档项目的受众。虽然我认为Sphinx是一个很好的工具，并会推荐它用于各种各样的文档项目，如果您的观众期待别的东西，请注意。例如，如果您正在记录Java项目，您的大部分受众可能期待Javadoc样式的文档。如果你偏离了这个期望，请确保它不仅仅是为了踢（也就是说，它给你的文档比你以前会更好），并准备（简单地）为你所做的不同做出的事情（例如，常见问题解答或介绍）。
All that said, be sure to consider the audience for your documentation project. While I think Sphinx is an excellent tool and would recommend it for a wide range of documentation projects, if your audience is expecting something else, be mindful of that. For example, if you were documenting a Java project, much of your audience may be expecting Javadoc-style documents. If you deviate from that expectation, make sure it's not just for kicks (i.e., it gives you better docs than you'd get otherwise) and be prepared to (briefly) make the case for what you've done differently (e.g. with a FAQ answer or introduction).
最后，任何文档比没有文档更好，不管用于创建它们的工具。使用任何可以帮助您的工具，如果它不是在某些东西之间的区别。
Finally, any documentation is better than no documentation, regardless the tool used to create them. Use any tool that helps you, if it's the difference between getting something out there and not.
这篇关于Sphinx为php代码文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
