LAMPlights Personal anecdotes from my experiences using the LAMP stack

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