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.

Checkout the existing php documentation and its tools.

Install required software

Mare sure you’ve installed the sqlite3 extension, required for PhD to work. On Debian or Ubuntu, use:

Install PhD, the PHP Document generator:

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.

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.

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 docbook files

Prepare the xml files you’ve generated and modified in the previous steps.

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.

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.