Looking for more information on how to do PHP the right way? Check out PHP: The Right Way

SitePoint PHP Blog:
Using Sphinx for PHP Project Documentation
Aug 17, 2015 @ 14:19:04

The SitePoint PHP blog has posted a guide to using Sphinx, a documentation generation tool that's used behind the scenes for the ReadTheDocs hosted documentation service.

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.

He starts with a quick "TL;DR" of the necessary commands to get things working quickly but follows it with the full details. He walks you through the installation of Sphinx locally, setting up the folders and adding a custom theme. He show how to create the table of contents, activate the PHP syntax highlighting and how to show/hide the "Edit on GitHub" links. He also includes the steps to convert Markdown documents into the reST format and, finally, adding the project to the ReadTheDocs site and pushing your results.

tagged: sphinx project documentation tutorial readthedocs markdown rest

Link: http://www.sitepoint.com/using-sphinx-for-php-project-documentation/


Trending Topics: