If you’re working on Open Source, documentation is king! However the process of creating documentation for a PHP C or C++ extension itself is not very well documented.
You’ve got some official source like a howto, some specific info for pecl. The official docs are or outdated or pointing in different directions. A found a good blog post by Kristina Chodorow, but it’s a bit out dated and still leaves out some steps. So here it is, an (other) attempt to a step-by-step guide for documenting your PHP extension written in C or C++.
Create a working directory and move in to it.
mkdir ~/phpdoc cd ~/phpdoc
Checkout the existing php documentation and its tools.
svn checkout https://svn.php.net/repository/phpdoc/modules/doc-en phpdoc
Mare sure you’ve installed the sqlite3 extension, required for PhD to work. On Debian or Ubuntu, use:
apt-get install php5-sqlite
Install PhD, the PHP Document generator:
pear install --alldeps doc.php.net/phd
Make sure your PHP extension is loaded. If it’s loaded the provided docgen.php script will use reflection to create a basic docbook files.
Replace my_extension with your extension name.
php ~/phpdoc/phpdoc/doc-base/scripts/docgen/docgen.php --output ~/phpdoc/phpdoc/en/reference/my_extension --extension my_extension
Add your extension to the master docbook file used to identify all available chapters.
Search for a section that matches the type of your extension. For example if it’s a database extension, move below the following tag:
Add a line in this section:
Prepare the xml files you’ve generated and modified in the previous steps.
php ~/phpdoc/phpdoc/doc-base/configure.php --with-partial=my_extension.rados
If configure.php generates any errors, fix them. It could be as easy as commenting out some lines with references to non-existing files.
Generate an HTML file from the XML-files.
phd -d ~/phpdoc/phpdoc/doc-base/.manual.book.rados.xml -o ~/phpdoc/docs/
By default no CSS is used in the html-output. You can easily create a php.net look and feel by downloading a style sheet from the site and include it in your html file.
cd ~/phpdoc wget http://static.php.net/www.php.net/styles/site.css phd --css ~/phpdoc/site.css -d ~/phpdoc/phpdoc/doc-base/.manual.book.rados.xml -o ~/phpdoc/docs/