Documentation is important, but commonly forgotten. Writing any code requires filling your brain with information – what the language is doing – what the API you’re calling is doing – what you want the code to do – and most of this information will fall out again a few days later. A month later a bug is found, and this information needs to be acquired all over again. Luckily you thoroughly documented everything that the code was doing, allowing you to pick up where you left off and fix the bug in seconds! Hurrah! Well, maybe.
phpDocumentor was the first PHP documentation system I met. It worked pretty well, although the format of the documentation it output left a little to be desired. A good example is the PHP Client Library for Google’s Adwords API.
This system is great, and I always include markup within code to allow simple documentation to be generated. Unfortunately it’s quite hard to write good documentation when it has to be wedded to the structure of a project’s sourcecode. The Zend Framework folks provide automatically-generated documentation, but also write a more thorough reference guide. I wanted a more sophisticated documentation generator.
Sphinx was originally created to create new documentation for the Python language. I’d always assumed it was only really suitable for Python projects, but soon started to see it in more places. The new phpDocumentor documentation is built with Sphinx (see the footer at the bottom), as is the current documentation for Zend Framework 2, and more PHP-centric projects seem to be making use of it.
I soon installed Sphinx and used its quickstart script to get going. Syntax highlighting of PHP source code is supported – Sphinx uses Pygments for this, but I was still lacking the ability to properly cross-reference code. Sphinx uses “domains” to allow you to document parts of the code such as classes or functions, and then allows easy cross-references between these. I found that the Python domain worked pretty well for PHP, but wondered if a better option was available.
Installing all this on Ubuntu is pretty simple:
sudo apt-get install python-sphinx python-setuptools sudo easy_install pip sudo pip install sphinxcontrib-phpdomain cd /path/where/documentation/project/lives sphinx-quickstart
After answering some questions about your project you’ll find a directory structure with an automatically generated conf.py. You’ll need to make a couple of changes to it as follows:
# Add any Sphinx extension module names here [...] extensions = ['sphinxcontrib.phpdomain'] # The name of the default domain. primary_domain = 'php' # The default language to highlight source code in. highlight_language = 'php'
Assuming you allowed the quickstart to create the makefile, you can now test everything works:
… and point your browser at the html documentation. Take a look at the makefile itself to see what formats you can use for your documentation – there’s a lot of options. reStructuredText itself is pretty simple, and the Sphinx documentation itself is good. Documentation for the PHP domain is OK, but misses some bits out. It allows you to document the following objects:
- ‘function’ cross-referenced with ‘func’
- ‘global’ cross-referenced with ‘global’
- ‘const’ cross-referenced with ‘const’
- ‘method’ cross-referenced with ‘meth’
- ‘class’ cross-referenced with ‘class’
- ‘attr’ cross-referenced with ‘attr’
- ‘exception’ cross-referenced with ‘exc’
- ‘namespace’ cross-referenced with ‘ns’
- ‘interface’ cross-referenced with ‘interface’
Now all you need to do is write something…