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.