Sphinx PHPdomain released

I’ve recently been working a fair bit on the new documentation for CakePHP and while sphinx is amazing, it doesn’t come with a built-in domain for generating PHP documentation. I decided that I wanted/needed one, as domains in sphinx give you a few great features:

  • Easy linking. By describing classes and functions with domains, sphinx lets you easily cross reference elements without knowing which file they are actually in. This makes links easier to make and more portable.
  • Free index. By describing classes and methods with a domain, you can automatically have an index generated for you, and included in your documentation.
  • Free formatting. Using domains gives you a bunch of useful free formatting that makes docmentation easier to read and use.

With all those advantages in mind, using a domain was a no-brainer really. There are a number of existing domains for various other languages. I used the Ruby domain by Yoshiki Shibukawa as the basis for the phpdomain. After a few afternoons of hacking away, I had a reasonable extension that let you do the following:

  • Document namespaces, classes, exceptions, constants, functions properties, and globals.
  • Cross reference all of the documented objects.
  • Generate an automatic index of all the documented objects.

Documenting a class looks a bit like the following:

Show Plain Text
  1. .. php:class:: DateTime
  2.  
  3.   Datetime class
  4.  
  5. .. php:method:: setDate($year, $month, $day)
  6.  
  7.   Set the date.
  8.  
  9.   :param int $year: The year.
  10.   :param int $month: The month.
  11.   :param int $day: The day.
  12.   :returns: Either false on failure, or the datetime object for method chaining.
  13.  
  14. .. php:method:: setTime($hour, $minute[, $second])
  15.  
  16.   Set the time.
  17.  
  18.   :param int $hour: The hour
  19.   :param int $minute: The minute
  20.   :param int $second: The second
  21.   :returns: Either false on failure, or the datetime object for method chaining.
  22.  
  23. .. php:const:: ATOM
  24.  
  25.   Y-m-d\TH:i:sP

You can set the description parameters, and return types for methods. If your methods take classes as their arguments, and you include that as the type for a parameter, sphinx will link back to the original class description.

The full documentation for the phpdomain is available on pypi and you can install the package using easy_install sphinxcontrib-phpdomain. If you want access to the raw source, you can get to it on bitbucket

Comments

OK Stupid question, can it auto generate the sphinx documentation or do you have to still generate all of this on your own?

If you can auto gen, how would you go about that?

Jonathan B on 4/5/11

Its not a stupid question really. For the PHPdomain, I didn’t implement anything that would generate API docs based on PHP source. However, such a package does exist for python code.

Implementing an automatic PHP documentation extractor for sphinx might be tricky, as you’d have to either parse or munge PHP code in python and pull out what you need. This additional complexity is the main reason I punted on implementing it.

mark story on 4/20/11

This has piqued my interest having started documenting an internal PHP project with Sphinx over the past few days. I’ve been looking for a way to incorporate the API documentation which is currently generated with DocBlox.

I may end up writing a custom transformation for DocBlox that generates the class documentation as reST files for use with your extension. It won’t be the most idyllic setup since it will rely on both Python and PHP, but it should do the job for us.

Jaik Dean on 5/17/11

Would you expect this to work straight off when installed, or would I need to declare I was using domains from sphinx-contrib in my conf.py? I’ve tried installing and using it and am getting unknown directive errors when I declare, say, php:class.

Douglas Greenshields on 5/23/11

By the way, this is what I did. I copied both the python and the compiled python files called “phpdomain” from my python site-packages directory (for me, C:\Python27\Lib\site-packages\sphinxcontrib-phpdomain\sphinxcontrib\) to the sphinx extension directory (C:\Python27\Lib\site-packages\sphinx\sphinx\ext\)

Then, in my conf.py file, I changed the extensions value to read the following:

extensions = [‘sphinx.ext.phpdomain’]

Then it worked for me. Hope it helps, and I’m sure there is a much easier way to do it.

Cameron Will on 8/2/11

If you set your extensions line to the following you won’t have to move any files:

extensions = [‘sphinxcontrib.phpdomain’]

Jaik on 9/15/11

Douglas Greenshields: As others have mentioned, you will need to add sphinxcontrib.phpdomain to your configuration file.

mark story on 9/17/11

Comments are not open at this time.