How to include tutorials in Phing-generated PHP Docs

This short article explains how Phing and phpDocumentator can be used together to merge DocBook XML tutorials into generated API documentation.

The Phing build tool provides a suite of powerful utilities for managing your PHP projects. One of the things Phing can do is use phpDocumentor to generate documentation for source code.

A not-often-used feature of phpDocumentor is its built-in support for add-on tutorials. phpDocumentor can take tutorials stored in DocBook XML and merge them into the set of documentation that phpDocumentor builds from source code. DocBook XML for phpDocumentor typically looks something like this (a seriously trimmed example pulled from QueryPath):

tutorials/QueryPath/QueryPath.pkg

<?xml version="1.0"?>
<refentry id="{@id}">
 <refnamediv>
  <refname>Using QueryPath</refname>
  <refpurpose>How to make the most of the QueryPath library.</refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <author>
   Matt Butcher
   <authorblurb>
    {@link <a href="http://querypath.org" title="http://querypath.org">http://querypath.org</a> Project Founder}
    {@link http://queryPath.org}
   </authorblurb>
  </author>
 </refsynopsisdiv>
 {@toc}
 <refsect1 id="{@id intro}">
  <title>About QueryPath</title>
  <para>
    QueryPath is a library designed to help you quickly and efficiently search,
    modify, and traverse XML and HTML documents. It is built on an interface with
    functions similar to what is found in {@link <a href="http://jquery.com" title="http://jquery.com">http://jquery.com</a> jQuery}. However,
    it is optimized for server-side work.
  </para>
  <para>
   The user guide for QueryPath is located in the 
   {@link <a href="http://api.querypath.org/" title="http://api.querypath.org/">http://api.querypath.org/</a> official site}. 
  </para>
  <para>
    Ready to get going? Start with the <emphasis>{@link qp()}</emphasis> function. Along with the 
    basic documentation, there are several examples linked from that function.
  </para>
 </refsect1>
</refentry>

The file above provides a basic introduction to the QueryPath library. It is in DocBook XML as described in the phpDocumentor documentation. We want to take the XML document above and have it integrated automatically into our API documentation.

Phing, the build tool, provides a target for generating source code documentation using phpDocumentor. One thing that is not obvious, though, is how Phing can generate tutorials.

Here's an example target configuration (an excerpt from a larger build.xml) that shows how the tutorials directory can be included in the phpDocumentor call. Tutorials included this way will automatically be read, parsed, and included in the generated documentation:

<target name="doc">
    <phpdoc title="My API Docs"
      sourcecode="yes"
      destdir="docs"
      output="HTML:Smarty:QueryPath"
      >
      <fileset dir="./src">
        <include name="<strong>/*.php"/>
      </fileset>
      <fileset dir="./tutorials">
        <include name="</strong>/*"/>
      </fileset>
      <projdocfileset dir=".">
        <include name="README"/>
        <include name="INSTALL"/>
      </projdocfileset>
    </phpdoc>
  </target>

The above shows a complete documentation build of a project. In the example above, the main source code is stored in a src/ directory, and all of the tutorials are stored in a tutorials/ directory. Of particular interest is this little section:

      <fileset dir="./tutorials">
        <include name="**/*"/>
      </fileset

This section instructs phpDocumentor to add the tutorials/ directory to the list of directories and files that phpDocumentor will process. The additional include element instructs phpDocumentor to include all subdirectories (**, and all files in each subdirectory (/*).

Based on this Phing instruction, phpDocumentor will analyze the tutorial DocBook XML files and generate HTML files, which it will link into the generated documentation.

Examples, too, can be added in a way similar to the method employed for tutorials. phpDocumentor can parse example PHP files -- files that illustrate how the library is to be used -- and include those files in the generated documentation. Should you want to add those, here is how you can do so:

    <fileset dir="./examples">
      <include name="**/*.php"/>
    </fileset>

Since examples are typically PHP files, phpDocumentor will process them just as it does any other PHP files.

Phing and phpDocumentor together provide a powerful method of automatically generating API documentation for PHP projects. In this short article, we have seen how tutorial documentation can be included in generated documentation.