Skip to content

Herman J. Radtke III

Updating PHP Documentation

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 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 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:  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

# use a sparse SVN checkout so all the languages and
# the tags and branches directories are skipped
svn co --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.