API documentation in Jenkins with DocBlox

People using PHP that want API documentation usually automatically think of phpDocumentor, which used to be the de facto standard for generating API documentation from your PHP projects. However, the project has been dormant for a long time now and definitely does not support new PHP features such as namespaces, so it was really time to look for an alternative. In this blogpost, I'll show you how I set up my Jenkins CI to use DocBlox, one of the new API documentation generators currently available.

First of all, of course, I needed to install Jenkins. This article is not about installing Jenkins, so I won't go into the details of that, but you can safely assume that I simply installed Jenkins on my Ubuntu VPS using apt-get. So this means that I now have a Jenkins user on my system, whose home directory is in /var/lib/jenkins (which is also the root of the Jenkins working directory). Next, I used the template of Jenkins-php.org to have a base template for my Jenkins projects. This saved me a lot of time in figuring out how to set up the build configuration for my project.

The only downside is that Jenkins-PHP assumes you want to use phpDocumentor for API documentation generation. I wanted to replace that with DocBlox, the API documentation generator built by my good friend Mike van Riel. One of the main advantages for me personally is the support for namespaces in DocBlox, that makes me want to use DocBlox over phpDocumentor. The projects that I am currently starting to use DocBlox for are not big projects, otherwise another reason would have been performance. DocBlox has been known to use far less memory and generate the documentation much faster than phpDocumentor. Anyway, I'm not here to sell DocBlox to you, I'm here to tell you what I did to set up DocBlox in the build process for Jenkins

So, to set up DocBlox is actually very easy. You just have to alter the build.xml template file that Jenkins-PHP has to replace phpDocumentor with DocBlox. Jenkins-PHP uses the following configuration for API documentation:

<target name="phpdoc"
        description="Generate API documentation using PHPDocumentor">
 <exec executable="phpdoc">
  <arg line="-d ${source} -t ${basedir}/build/api" />
 </exec>
</target>

Instead of that configuration, I now use:

<target name="docblox">
  <exec executable="docblox">
    <arg line="project:run
               -d ${source}
               -t ${basedir}/build/api" />
  </exec>
</target>

You will have to make sure to remove the phpDocumentor antcall in the parallelTasks target, and call the docblox antcall instead:

<antcall target="docblox"/>

If you've done all this, then Jenkins should make sure that DocBlox documentation is generated. If you want to see the full build.xml that I'm currently using for my phpOpenNOS project, then check here.