phpDoc to WordPress

phpDoc to WordPress exports documentation generated by phpDocumentor 2 into WordPress. Download from Github.

How it works

You transform an XML file from phpDocumentor using a supplied XSLT file, which converts the XML into a WordPress export file ready for import into your WordPress site. Browse the Achievements documentation to see an example.

What’s in the box

  • Two XSLT scripts; one to make an import file for classes, the other to make an import file for functions and methods.
  • A WordPress plugin which sets up three custom taxonomies used by the imports; versions (mapped to phpDoc’s @since), contexts (hardcoded to “developer”), and types (used to further categorise what type of item is being documented; hardcoded to “classes”, “functions”, or “methods”).
  • My Achievements plugin‘s current structure.xml file, as a sample for your convenience.

Recommendations

  • Use the included plugin to create the custom taxonomies on your site.
  • Download the WP Re-Importer plugin from WordPress.org and use it to import your documentation.
  • Create a pair of pages (e.g. “Function Reference” and “Class Reference”) to make your URLs look pretty.
  • Though these tools are still very young, it’s become apparent to me that it’s as only as good as the quality of your phpDoc. If the generated pages have sucky content, first check that your phpDoc markup doesn’t suck.
  • If your project has a function or method with the same name as a class, you’re screwed.
  • Please please please test on a dev site; you’re probably going to be importing hundreds of new pages, and you’ll find things that you want to tweak.

Instructions

  • Use phpDocumentor 2 on your PHP project. In its output folder, grab the structure.xml file.
  • Grab a XSLT 2.0 compiler (i.e. Saxon); I recommend Kernow. Use it on your structure.xml and transform it with the make_classes.xsl and make_functions.xsl files. You’ll generate two new files; these are your WordPress export files.
  • Go into your WordPress site and create a “Function Reference” and “Class Reference” page.
  • In the WordPress admin, go to the Tools > Import screen. Choose the “WP Re-Importer”. When importing, disregard any warnings about missing authors.
  • Import your classes export first and use “Class Reference” as the parent page.
  • Import your functions export second and use “Function Reference” as the parent page.

You’re all done! Review your new documentation, and then let me know your friendly opinions!

3 thoughts on “phpDoc to WordPress

  1. This is actually pretty awesome. I’m looking for something like this for one of the PHP class I’m working on, but also would like to take advantage of the WordPress SEO. Please keep it going!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s