Generating PHP code documentation with Sphinx? [closed] - php

Question

Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this 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/

Answer 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.

Answer 2

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

Answer 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.

Answer 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'

Answer 5

As far as I'm concerned, you can document just about any syntax in Sphinx as far as you doesn't limit yourself with languages supported by autodoc. You can create beautiful API References using standard Sphinx directives like .. class, .. method, .. function and other. They work perfectly apart from the source code and doesn't require any automatic generation and linking to the sources.
You can also create generic admonitions with some special class, that you could later hook to CSS:
.. admonition Title
:class: Ololo
This text could be formatted any way you want, using the ``Ololo`` tag.
There are also roles (they allow custom classes too) and other means of adding text with some special formatting, if the original directives aren't sufficient to you.
If you decide to create your docs async from the source code, make sure you disable checking the code coverage and other code-related features in your conf.py or on project initiation.
PS: You can see a very good answer on elements with custom classes here.