Generating PHP code documentation with Sphinx?

Question

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?

https://www.sphinx-doc.org/en/master/

Solution 1

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.

Solution 2

Just released a few days ago: http://mark-story.com/posts/view/sphinx-phpdomain-released

Solution 3

CakePHP is using Sphinx for its new documentation, and I wrote the phpdomain for sphinx. While there isn't a way to automatically include your php doc blocks into sphinx, I still think its one of the better documentation authoring tools available. Its great for more narrative style documentation. But with the phpdomain you can make api docs as well.

Solution 4

The Doctrine project, an ORM for PHP, uses Sphinx to generate their online documentation at www.doctrine-project.org. They use a custom pygment for PHP. The documentation is available on Github at https://github.com/doctrine/orm-documentation. It includes the custom PHP pygment css file.

Also the python-pygments package comes with many pygment styles which you can try out by changing the pygments_style = value in your sphinx conf.py configuration file. For example, to try out the pastie highlighting sytle, which is part of python-pygments, you use

pygments_sytle = 'pastie'

View more solutions