Lone Wolves

The longer I program, the more structured my programming methods have become. Gone are the days of editing live spaghetti code directly on the server or frantic FTPing files after each tiny change. Today I not only stuff everything in Subversion just to keep track of changes, I also use it as a deployment mechanism. But I want more and I want it automated too! Currently I am busy playing with generated documentation and unit testing. Generated documentation is an all round great idea, but it has a drawback: You need to generate it all the time. So I set out to use Subversion’s post-commit hook to generate fresh documentation for my PHP projects using phpDocumentor.

I have written a little Python script that you can call from Subversion’s post commit hook. This script scans your subversion project for files that have the phpdoc property set. If any of these have changed, then it regenerates your documentation using phpDocumentor. It can also deal with files that are not kept in your Subversion repository and supports anything also supported by phpDocumentor.

Uh, a Python script? For a PHP application?

Well, yes. I have two answers for that, a long one and a short one. The short one is “Meh.” The long one is “It doesn’t matter.” Both Python and PHP are great languages to write little commandline scripts with, each having features the other one doesn’t have. Python’s list comprehensions make for beautiful concise code while PHP’s arrays are just much more flexible. Python’s exception handling is vastly superiour to PHP’s haphazard error handling, but lack of an ordered dictionary in Python make certain applications (such as SOAP support) hard. Okay, enough of my little Python versus PHP rant and back to generation documentation.

Configuring post-commit-phpdoc.py

You can check out the post-commit-phpdoc.py script in my Subversion repository or download it directly. To check out the latest version, use:

Put it somewhere convenient and execute it with the --help flag to see the documentation.

Setting up the post-commit hook is quite easy. First, you need to create a directory where you want to store the generated documentation and a checkout of the project. After each commit to your project, the post-commit hook will update the checked out copy and use it to generate documentation. Because everything happens as in the post-commit hook, you should create everything as the user your subversion server runs as, e.g. the svn user or the www-data user.

Next, check out a working copy of your project to the checkout directory. You don’t need to checkout the entire repository. Just checking out the portion that you want to generate documentation from is enough.

Now you can setup the post-commit hook. Create a new executable file called post-commit in your repository’s hooks directory, or modify your existing post-commit hook. Append the post-commit-phpdoc.py command.

The --repos and --rev options are the variables passed by subversion to the post-commit hook. The --checkout-path path should point to the checkout you made above. The --svn-path should contain the path inside your subversion repository that you checked out. In this example, we checked out the trunk directory. Everything after the -- switch is passed straight to phpDocumentor. Read the phpDocumentor manual to learn about it's options.

There are a few extra arguments that you can pass to post-commit-phpdoc.py that can be useful. With --pre-update and --post-update you can point to an executable that should be executed just before or just after the post-commit hook updates the checked out repository. This is useful for clean-up or GNU make actions for example. With the --include and --exclude options you can filter what files will have their svn properties checked. This can be used to filter out ubversion branches or tags for example. For instance, if you have a subversion repository containing multiple projects, but you want one big documentation for all of them:

You can make a checkout of your entire repository to the checkouts directory, then pass --include=*/trunk/* as an option to only generate documentation for the trunk of each project. Note that --exclude works before --include, so if you exclude a certain portion of your checkout, it will not be checked to see if it contains anything that should be included after all.

Finally, there is also a --debug switch. When you turn this on, all the script’s output is logged to stdout, such as the output from svn update or the phpdoc command.

Tagging your PHP files

Once you have configured post-commit-phpdoc.py you can start tagging your PHP files. post-commit-phpdoc.py looks for files and directories tagged with a phpdoc property. If you tag a file with phpdoc then that file will be included in the list of files that phpDocumenter uses for documentation. The content of the phpdoc property can be empty. It's ignored by the post-commit hook.

If you use the phpdoc property on a directory instead of a file, then you can set the property content to a comma separated list of files and use wildcards as well. This is useful to include generated PHP files or other files not committed to your subversion repository. Take the following subversion tree for example:

In here, the Makefile generates bar.php from bar.php.in. If you wanted to generate documentation from it, check out a copy of the tree from subversion and set the following svn properties for example:

After this, commit your working copy and watch the documentation being generated on your subversion server. Simply create an Apache virtual host or a symbolic link from /var/www to the target directory you passed to post-commit-phpdoc.py to view your documentation online. That's all there is too it. Happy coding!