phpDoc to WordPress exports documentation generated by phpDocumentor into WordPress. Start using it today.
The best way to produce useful documentation for PHP code is to annotate it with phpDoc tags and keywords. Based on javadoc, phpDoc goes beyond a straightforward description of what something does, and allows the developer to add extra information which will help others who read the code to quickly understand its most important aspects. For example, a function can marked up to say when it was added to a project, its arguments types, and its return values.
From this phpDoc markup, the phpDocumentor app is the best way to generate standalone documentation that you can distribute with your project or make available as a reference on your website. But what happens when you want this documentation inside your WordPress?
Documentation generated by the phpDocumentor app does not aim to be a replacement for conventional developer documentation, but supplements it. If we only consider developer documentation for example, there should still be a place for user contributed documentation such as helpful observations or usage examples.
My two preferred ways of doing this are either wikis or using a CMS that everyone can publish to. Wikis, of course, are all about a collaborative approach to writing; WordPress’ documentation, the Codex, uses MediaWiki. bbPress and BuddyPress take the other approach, and both use a WordPress site in which every user is an Editor. I note that the upcoming WordPress Handbooks are built inside WordPress.
For my Achievements plugin, I decided to use my WordPress site as a place for my developer and user documentation, and I wanted to start by getting the class, function, and method documentation generated by phpDocumentor into WordPress.
The solution I am releasing today consists of a XSLT script that reads an XML file from phpDocumentor, which contains the structure of the phpDoc markup, and transforms it into a WordPress export file ready for import onto your WordPress site. Browse the Achievements documentation to see an example.
If you want to try this on your own project, read the phpDoc to WordPress instructions to get started. I’d like to thank @laurabygaslight for help getting started with the XSLT; any egregious mistakes in it are all my fault.
Where does this tool go from here? If there’s interest, I’d like to investigate ways of easily giving people a good WordPress-powered documentation site, but it depends on how well this is received, and if anyone wants to collaborate. Get in touch!
Paul Gibbs 