The ABC's of Google

A is for Android
B is for Buzz
C is for Chrome
D is for Docs
E is for Earth
F is for Finance
G is for Groups
H is for Health
I is for Instant
J is for jQuery
K is for Knol
L is for Latitude
M is for Maps
N is for News
O is for Orcut
P is for Profile
Q is for Quick Search
R is for Reader
S is for Search
T is for Talk
U is for Uncle Sam
V is for Voice
W is for Webmaster
X is for XMPP
Y is for YouTube
Z is for Zitegeist

Automated Documentation Generation

When it comes to projects that I am working on, I tend to love tools that help me develop better software.  My favorite open source developer website is Ohloh, which provides insights into code statistics.  Since my projects are hosted on Google Code and Github the code browsing, issue tracking, and wiki pages are already covered. The missing link has been generating the source code documentation such as Javadocs.

All of my projects are hosted in a Subversion of Git repository, so it is just a single command to get the most up to date code.  Generating the documentation on my server allows for an automated approach to get up to date documentation on by website.

A few of my projects are written in Java, so generating Javadocs is exactly what I did.  The difficulty in this task was getting my server to compile the Android and App Engine projects.  After some tinkering, I managed to get the correct files and configuration set up on my server.  When executing the Javadoc command, it is necessary the the project be compiled.  This documentation is excellent and matches the standard for almost all Java projects.

I also have a few open source PHP web application that I have created.  For these projects, phpDocumentor provided a method to generate documentation that is similar to Javadocs, but is specifically geared towards PHP.  The documentation for these PHP applications is not as robust as Java, mainly due to the nature and design of the language.  My PHP based projects are lacking in function and class header information making these documents less useful.  In the future I may find some time to work on refactoring and fully documenting these projects.

Lastly, I have some open source C# applications.  These applications are the best documented applications because of my use of StyleCop which enforces strict coding standards.  Older versions of Visual Studio had built in functionality to generate HTML documentation.  This has replaced with NDoc, which has been replaced with Sandcastle.  These solutions had the major downside of only running on Windows, my website runs on Linux.  Based on the limitations of these other approaches, I went with Doxygen to generate C# documentation.

Doxygen is capable of generating html based documentation from a variety of languages without the need to compile the code.  After some customization, Doxygen generates robust HTML based documentation.  While it would be possible to generate the Java and PHP documentation using Doxygen, it is not as a tuned approach for those specific languages.  For the specific requirements of documenting a C# application, it is the best solution.

The current implementation generates new documentation for my opensource projects every night based on a single script.  My next goal is to write some logic that checks for updates every night, but only regenerates the documentation if there were changes made to the source.  Overall I am very pleased that I have found a solution for all of my projects and will continue to work on improving my commenting and documentation practices.

Switching to EC2 Hosting for my Personal Website

I had been using a GoDaddy shared hosting account for my personal website since I created it, but recently changed things up. With Amazon announcing their EC2 Micro instances, cloud based hosting was within my price range. The cost of running the VM is $0.02 per hour, totaling around $14.40 per month. There are some other costs including storage and bandwidth, but they will likely total less than $2.00 per month. What it comes down to is I have my own personal install of Linux to host my web site!

This does come with some down sides.  The VM is slow, specifically the CPU.  It comes with 613 MB of RAM which is plenty for my purposes.  Since my website doesn't receive that many visits the speed is not a major concern of mine.  However, I have determined that the micro instance isn't powerful enough to handle my install of ThinkUp because the database is just too large.  This is disappointing, but I will create a new install on my Linux box and run it locally.

The reason I can justify paying twice as much for hosting is the benefits that I get from having root on the Linux box.  While it means I have to do more Linux administration, it also means I can run whatever software I want!  Specifically, I have set up a personal SVN server that I am using for class projects.  I use both Google Code and Github for open source projects, but my class projects never had a home until now.  So far it has worked out with no problems and using WebSVN provides me with a useful way to browse and analyze my code.

I have migrated my backup script to the new setup and switched to using s3cmd to transfer files to Amazon S3.  With the additional services provided on the server, the script now includes a backup of the SVN repositories and the server configuration files.

While this does mean that I will be paying more, the additional features should justify the cost.

Almost there...

This is my last fall semester as a college student.

Wow.

Automated Generation of Javadocs for Open Source Android Applications

While Java is not my favorite language, it has its benefits. With one Android application already posted on the market and another application in development, I decided to start using Javadocs a little more seriously. The process of generating Javadocs is not that complicated using Eclipse, but that is not the solution I wanted. My goal was to automate the generation and posting of the docs as the source code changed.

My shared web host was suitable for hosting the html files, but not running javadoc to actually generate new documents. The solution I came up with was to automatically download the latest code from my public repository, generate the javadocs, and then upload the html files to my shared host. The computer I executed this code on was a Linux virtual server that I have sitting around. The process was actually very simple:

1. Clean up any files from the previous run of the script
2. Download the latest source code from the svn repository using svn export. It is notable that you can use svn export with Github since they support accessing repositories using the SVN protocol. Awesome!
3. Generate the javadocs based off of the freshly downloaded code using the desired parameters.
4. Copy the newly generated javadocs to the desired server. For my purposes, secure copy was the best solution. With my server's public key installed on the shared host, I was able to log into the remote box without prompting for a user name and password.

The final step in the process is to simply run the script nightly with a cron job and the javadocs will always be up to date. Since I was generating documents for Android applications it was important that the Android jar file be located on the server and the javadoc command be made aware of its location. Without this jar file, the generated javadocs would be incomplete. It is necessary that the Java code can actually be compiled on the computer where the javadoc command is run.

Here is the bash script with the file paths changed to protect the innocent:


#!/bin/bash
cd /path/to/files/docs/
rm -rf ampted.svn
rm -rf ampted

svn export http://ampted.googlecode.com/svn/trunk/
mv trunk ampted.svn

JAVADOCHEADER='<a target="_top" href="http://www.amptedapp.com/">Android Mobile Physical Therapy Exercise Documenter</a>'
JAVADOCFOOTER="Generated on `date`"
javadoc -private -header "$JAVADOCHEADER" -footer "$JAVADOCFOOTER" -d /path/to/files/docs/ampted/ -sourcepath /path/to/files/docs/ampted.svn/android/src/ -subpackages com.AMPTedApp -classpath /path/to/files/lib/android.jar

scp -r /path/to/files/docs/ampted remoteuser@example.com:/path/to/remote/files/docs/


This process has one point where it could definitely be improved and that is that it always overwrites the javadocs even if the source code did not change. If a check was added that compared the commit number of the previously generated documentation and only generate and upload a new copy if it is newer. This wasted effort is not a major concern for small projects, but may need to be fixed as my projects grow in size.

You can see the docs for AMPTed, which is a project that is in the very early stages of development, at http://javadocs.amptedapp.com/