Jeroen Moors

blog

Documenting your php extension
Written on 18 June 2013

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 environment

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

Install required software

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

Generate a docbook skeleton

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

Update the main index

Add your extension to the master docbook file used to identify all available chapters.

Edit ~/phpdoc/phpdoc/doc-base/manual.xml.

nano ~/phpdoc/phpdoc/doc-base/manual.xml

Search for a section that matches the type of your extension. For example if it’s a database extension, move below the following tag:

  
    &VendorSpecificDatabaseExtensions;

Add a line in this section:

&reference.my_extension.book;

Prepare the docbook files

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 HTML

Generate an HTML file from the XML-files.

phd -d ~/phpdoc/phpdoc/doc-base/.manual.book.rados.xml -o ~/phpdoc/docs/

Pimping your HTML

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/