Using Sphinx for PHP Project Documentation
I recently had the need to write proper prose-like source-code documentation for the Diffbot PHP client. Having looked at several documentation generators, and even having suggested a @prose tag for importing of related MD/reST documents into method and class descriptions, I realized there simply is no perfect solution we can all agree on (yet). So until I extend Sage with a @prose token and reST parsing, I opted for ReadTheDocs and Sphinx.
RTD is widely used in the industry. It hosts powerful docs such as Guzzle’s, PhpSpec’s and many more. It supports reST alongside MD (or, to be more accurate, MD alongside reST), which is a huge plus as RST files are more suitable for highly technical documents. It can be run locally and generate offline-friendly HTML files, but it can also compile from documentation source available online and and be automatically hosted as a subdomain of readthedocs.org.
That said, setting it up for a PHP project has some caveats, so we’ll go through a basic guide in this tutorial.
TL;DR
If you’re just looking for the list of commands to get up and running quickly:
Continue reading %Using Sphinx for PHP Project Documentation%
LEAVE A REPLY
You must be logged in to post a comment.