Herman J. Radtke III

Read more of my blog or subscribe to my feed.

Updating PHP Documentation

Written by Herman J. Radtke III on 05 Dec 2010

I sometimes help update the PHP documentation.  I have not done it in a while since I started maintaining pecl/memcache.  However, there was a recent bug submission where I felt the documentation for pecl/memcache should be updated.  A lot of work has been done to the documentation tools since I last updated documentation.  I went to http://doc.php.net for a quick primer on how to generate some new documentation output so I could test my changes and found the documentation for generating documentation a little hard to follow. PHP documentation generation is done in two steps.  First, you need to generate the docbook file.  You somehow have to find this page http://doc.php.net/php/dochowto/chapter-configure.php that explains how.  Once the docbook file, normally called manual.xml, is generated you have to actually generate the documentation output.  I found the PhD manual here: http://doc.php.net/phd/docs.  PhD can create a number of different documentation formats from the docbook file.  I normally just use the xhtml output and serve the page up on my local web-server to verify my changes.  I found section on rendering to be a little hard to follow.  Here are the steps I used to update the content on the Memcache:getExtendedStats page:
sudo pear install doc.php.net/phd-beta

# use a sparse SVN checkout so all the languages and
# the tags and branches directories are skipped
svn co http://svn.php.net/repository/phpdoc --depth empty phpdoc

# checkout the documentation toolset
svn update phpdoc/doc-base --set-depth empty
svn update phpdoc/doc-base/trunk --set-depth infinity

# checkout the english version of the documentation
svn update phpdoc/en --set-depth empty
svn update phpdoc/en/trunk --set-depth infinity

cd phpdoc
vim en/trunk/reference/memcache/memcache/getextendedstats.xml

# generate the docbook file
# disable libxml check as Cent OS 5.5 does not have LibXML version 2.7.4
# put the docbook file in the root phpdoc directory
php doc-base/trunk/configure.php --output=manual.xml --disable-libxml-check

# generate xhtml output in the output/ directory
phd -d manual.xml -f xhtml
Note: you can safely ignore the E_USER_WARNING about "Image does not exist" when generating the output.