Posted on

ApiGen versus phpDoc

So last night I went down the path of connecting phpDocumentor2 (phpDoc) to my code so I can find key elements in the classes and objects without having to search through the code editor. That works fine, but it is often faster for me to have an index of the classes, methods, and properties in a browser window. Even better, by publishing on the public CSA site I know can use Google to search my own docs. That is a nice bonus.

This morning, while researching custom templates, I came across a competing tool that threatened derailment of my phpDoc efforts. I came across comments that phpDoc was inferior, not updated, and had poor documentation. The project had been ignored for a few years. Turns out that much of that has been addressed since the phpDoc efforts have continued once again, though there are still plenty of gaps in the documentation of the phpDocumentor2 tool kit. After a brief run with ApiGen, I am back on the phpDoc trail.

Official Website

I was a bit apprehensive about ApiGen from the start. Why? The official website for ApiGen seems less polished than the phpDoc site. If they can’t make a great first impression on their website, what are the chances they can create decent HTML docs from my code comments? Turns out I liked the generated HTML better than their website. While phpDoc does have holes in their website presentation as far as features sets, command line options, etc. It is easier to find what I am looking for and seems to have much more documentation online than ApiGen. Maybe ApiGen has more documentation, but if it is not easy to find that doesn’t make me more efficient.

Winner: phpDoc

Installation

The installation of both products was about the same.   Use pear to setup a remote archive, and run pear to install the product.    However there was one or two fewer steps in installing phpDoc over ApiGen.   The big difference, however, was the facilitators required by ApiGen versus phpDoc.  phpDoc required far fewer libraries and add-on packs than ApiGen and produces better results.    phpDoc is either utilizing more of my CentOS 6 default PHP libraries or it just needs less in the “other frameworks” department to accomplish a similar goal.

Winner: phpDoc

NetBeans Integration

As for the NetBeans integration, they are both fairly similar.  Neither option functions very differently from the other.   They both need a target output directory set.  However, for some reason ApiGen requires you to locate the full path to the executable.  phpDoc just automatically worked.  Slight advantage: phpDoc.

Winner: phpDoc

Generated Site : Weight

This is one place where I think ApiGen wins out.  The overall “weight” of the produced site for the code documentation has less stuff to push around to and from the public server.  That also means that the stuff the pages have to load when people are viewing the site is less.   However I think there is a trade off on quality and possibly mobile-aware presentation.   Based on sheer “bits and bytes” to get the page online, ApiGen is lighter.

Winner: ApiGen

Generated Site : Quality

While I do like the search feature of ApiGen, I quickly discovered it is not a general “search any word” type of search we all are accustomed to on any site.  It is more of a “type a few characters and find a class name” search.  At least out of the box that is how it seems to be configured.   So while the search feature seemed like a plus, it really isn’t that useful to me.     Overall the look and feel plus ease of navigation of the phpDoc generate site works better for me.

Winner: phpDoc

Summary

Overall, I found phpDoc to be the best option at this point.   ApiGen isn’t bad, but today phpDoc edges out ApiGen in the areas that matter most to me.

You can compare the results of my simple Tagalong test here:

Tagalong Code Docs from ApiGen

Tagalong Code Docs from phpDoc

Posted on

Geeking Out With Netbeans and PHPDoc

I’ve been playing with phpDoc and NetBeans a lot lately.  I’ve found that having well documented code using the phpDocumentor 2 format makes for a much more efficient coding environment.   For one thing, if you have NetBeans setup properly and are using PHP classes that are fully documented, writing a line of code is as simple as typing a few characters.  NetBeans will find the objects you are looking for and list the properties and methods as you type.

That makes for some fast coding when typing something like $this->plugin->currentLocation->MakePersistent().  When everything is setup properly and the classes are properly documented I can type $t<tab>p<tab>c<down><tab>M<enter>.    While it may look like a lot of typing when spelled out essentially I am typing “$ttptcdtme”, or 10 characters instead of somewhere around 70.    Being 7x as efficient when writing thousands of lines of code is a HUGE bonus.

GitHub Markdown Docs for Code

Auto-complete shortcuts alone is one good reason to use a strong IDE like NetBeans along with a good code commenting/documentation solution like phpDocumentor2.   However tonight I found a cool new trick that I stumbled upon while trying to generate code documentation via GitHub.    I had learned a couple of weeks ago that I could use the command-line PHPDoc tool and a open source GitHub project called PHPDocMD to convert my code comments to XML and convert that to markdown (MD) that GitHub likes.   It creates OK results that are out on the public code repositories at Github.

So what is that new trick?  Well, there are 2 distinct parts.

Autogenerated HTML Docs for Code

Turns out there is a plugin for NetBeans that I’ve been ignoring.  For some reason I just happened to figure out that the “Generate Documentation” menu that appears when I right-click on a project in NetBeans actually has some use.

Yeah, I’m slow like that sometimes.

Turns out that under that menu is a submenu that has “ApiGen” and “PHPDoc” listed there.    Interesting.    That could be useful.

I went to the project, right-click, and select properties.  Sure enough, there is a setting for “PHPDoc” and it asks for a destination directory.  Basically asking “where do you want me to dump all the auto-generated documentation for your project?”.    Well it turns out that during my journey toward publishing code documentation on GitHub with MD, I had cloned the GitHub documentation repository to a local path on my development system.   I already had a folder full of code docs for my main plugin as well as several add-on packs.   So I pointed the output for my Netbeans “PHPDoc” setting to go there.

I go back, right click on the project, and select the Generate Documenation/PHPDoc.

Sure enough, NetBeans crunched my code comments and a few minutes later my Firefox browser window pops open and I see a pretty darn cool HTML site on my local box that has a full navigation menu for all of the classes I am using in my project, the properties, the To Do lists from my comments and more.  All this created because I’ve been taking a bit more time to fully comment the code.  Nice!

Settings Up For Auto-Publishing

Ok, so now on my dev box I have some pretty nice code docs that I can generate with a couple of mouse clicks.   That is helpful with a large project with multiple add-on packs.   But then I start thinking, why just keep it local?   The code is open source.  I have other developers that want to learn how to tweak the code for their own purposes.  I have third party developers looking for documentation and examples on how to do things so they can write efficient add-on packs.    Why keep the info all locked up on my dev box?

Well, I learned a neat trick a couple months ago with NetBeans.    I can have a local git repository on my development system but setup NetBeanswith a new “remote source” project.

So here I am with my commented code in my WordPress plugin directory that is fully commented and connected to a GitHub repository.   In another “docs only” directory outside of WordPress I have my PHPDoc generated HTML and MD files that I was previously only publishing to GitHub Wiki Pages, but now thanks to NetBeans I am also surfing locally on my dev desktop.     I realize I can auto-publish these code docs to my public website.

I create a new NetBeans project right next to my plugin code project.   I call it “store-locator-plus-codedocs” and set it up as a new PHP Remote Source project.   I tell it the local source on my box is the folder that I was storing the PHPDoc and MD files in for GitHub, which now contains my NetBeans-generated HTML files as well.    For a remote location I tell it to use my SFTP connection to the Charleston Software Associates website.  I jump on my website and make sure there is a new codedoc directory with a blank readme.txt file there.  If you don’t have SOMETHING for NetBeans to download from the remote source it thinks you screwed up and won’t continue…. minor flaw IMO, but easily remedied.    I then click OK.  It shows me the readme.txt with a checkbox to download it.    Click OK and BAM… there is a new project with the blank readme.txt plus all of the MD and HTML documents that were already on my local dev box.

OK, so kind of “so what” at this point, but here is where it starts getting cool… at least from a geek perspective.

Push The Initial Content

Now I need to “seed” the public website with the already-created content.   In NetBeans it is easy enough. Just highlight all the files in the project, right click and select upload.    Within a few minutes the entire HTML sub-site is uploaded to the server.   Just like any FTP program.   Nothing to it.

However now if I make any changes to those file with the editor two things happen, it saves a local copy on my dev box and it auto-publishes that updated to the live server in near-real time.    Since my local dev box has version control via GitHub, I can also quickly commit and push those edits also from inside NetBeans and make sure they are saved to the code repo.

But… I’m not going to ever edit those docs by hand.  They are auto-generated code documents that come from my well-formatted comments.  So the RIGHT way to edit them is to continue cleaning up and augmenting the code comments to make sure they are PHPDoc compliant.

So that is kind of cool.  My code docs are now auto-posting to my live server, saving on my dev server, and are one click from being saved and committed back to GitHub.  I can even add on more step and create a second copy in MD format for publication right next to the source code on GitHub.

But this is what really made me think “shit this is kind of cool”…

Auto-Publishing Code Comments

So I have all this stuff setup, my code project and my documentation project are both open at the same time in Netbeans.    I forget all about it as I start getting back into code writing.     I edit a method for one of the add-on packs and of course I go and update the comments about that method to reflect the latest changes.  I see another comment that is not complete and fill that out.

Save the code.  Commit the code so it publishes to GitHub.

A few more edits to code and comments later I decide… let’s generate the documentation before I sign off tonight…

I right click on my code project and select “generate documentation”.

Auto-magically the documentation project updates itself.   It saves a copy locally to my dev box with the new docs in place then auto-publishes to the public website with no intervention on my part.   As I setup the rest of my plugins with this system you will be able to find all the code docs on the bottom of the Technical Docs page on my site.   You can see my first auto-published work for Tagalong here, though I’m nowhere near done cleaning up the comments and naming conventions on my method to make this all “gussied up” for public consumption, but it’s a good start.

Maybe I’m just extra-geeky, but I thought that was cool… especially when the code docs actually look pretty darn good IMO, especially since they were created from nothing but /** This method does something.  @var string $this – does that **/ comments in the code.

I also know that with a few lines of script I can not only save locally and publish nice looking docs to my public site but also commit the code back to the GitHub repository while auto-generating the duplicate MD docs for the GitHub Wiki.

Yeah, I’m a Code Geek… and I’m not ashamed to admit it.

Posted on

Making GitHub Wiki Docs From PHP Source

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

$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.