I’ve been using NetBeans to write my PHP-based WordPress plugins and have found that well crafted PHPDoc comments make a notable difference in the efficiency of my coding. I’ve written a post-or-two about that and find the auto-fill features to be very helpful. I have also noticed that much of the WordPress core also follows PHPDoc conventions, so using PHPDoc is a good way to comment your WordPress plugin code IMO.
The other tools I use frequently are GitHub with SmartGit. While git had a steeper learning curve than subversion, I much prefer the lighter “differential data” standard of git as well as the distributed repository concept. Both just “feel” smarter. The next logical step from tracking code commits and issues with GitHub was finding a home for my code documentation. I really didn’t want to manually great web pages from the PHDoc raw HTML. I also didn’t want to write a plugin to read PHPDoc to get the content into my website, so I went on a quest to find the tools needed to publish my PHP comments right on the GitHub wiki pages. After a long search I finally found the pieces of the puzzle I needed to go from PHP comments to GitHub wiki pages with limited effort. The process is outlined below.
Clone Your GitHub Wiki Pages
- Go to your GitHub project and look for the Wiki tab. If you do not have it, especially for an older project, you may need to enable “pages” in the repo settings at GitHub.
- Under the Wiki tab is a sub-tab for “Git Access”. It has the WIKI repo URL, which will automatically be attached to the parent project under the wiki tab.
- Clone this to a new directory on your dev box.
- (BTW, this step is optional, this is just how I opted to do this, keep the docs OUT of my main code repo).
Setup/Build The PHPDocMD Tool
- Go clone PHPDoc-MD into a clean directory on your dev box: https://github.com/evert/phpdoc-md
- Go to the new PHPDoc-MD directory and go to the src directory.
- Go clone Twig under there to a directory name Twig: https://github.com/fabpot/Twig
- Tweak the PHPDoc-MD code, just edit the ./bin/phpdocmd file so the top looks similar to this:
$docmdDir = dirname(<strong>FILE</strong>);
set_include_path(get_include_path().PATH_SEPARATOR.$docmdDir.'/../src/Twig/lib');
// Potential composer autoloader paths $paths = array( $docmdDir . '/../src/PHPDocMD/Parser.php', $docmdDir . '/../src/PHPDocMD/Generator.php', $docmdDir . '/../src/Twig/lib/Twig/Autoloader.php', );
foreach($paths as $path) { if (file_exists($path)) { include $path; print "including $path\n"; } }
Twig_Autoloader::register();
// Everts crappy option parser.
These code edits are necessary because the tool is not refined yet. It was clearly setup for the developer’s system which has Twig installed and a vendor autoloader file that is not in the git repo. Not a big deal, easy enough to get around if you follow the steps here.
BTW, that last comment is his, not mine. I left if there so you know where to stop the edit.
Use PhpDoc & PHPDocMD
You may want to symlink that phpdocmd to your /usr/bin directory so you don’t have to type the full path every time, but now you just need a few steps to create GitHub Wiki compatible doc files:
# phpdoc -t . -d .That creates the structure.xml file needed to generate the MD files.
Then run this command:
# phpdocmd ./structure.xml <path to your github WIKI project>Now your GitHub Wiki Docs project should be full of MD files that reflect your code PHPDocs. Just push your GitHub Wiki files back to the GitHub server.
