views:

615

answers:

1

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

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?

http://sphinx.pocoo.org/

+7  A: 

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.

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.

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.

ddbeck
I wanted to post my answer but this one is so comprehensive that I don't have anything to add :)
Adam Byrtek
Also note that Sphinx 1.0 (currently beta) has support for "domains" in order to help with documentation in various languages (support for specific language constructs, etc.). I don't think there's a PHP domain yet, but I'm sure there will be in the not-too-distant future.
Kevin Horn