Having quick access to API documentation is one of the absolutely essential requirements during my development day. I have knowledge of so many different technologies, APIs, syntaxes, runtime behaviours, protocols, editing environment commands and shortcuts crammed into my head that I’m well beyond having perfect recall of every single detail of whatever I happen to be working with. At the start of my Ruby programming adventures, I was always trawling through the online Ruby and RoR documentation, either using Google to find references or Firefox’s inbuilt page search to find a method, module or class in the framed documentation lists. This was wholly unsatisfying, particularly with how web browsers search through frame-sets. I also seem to have a major personality defect in which I will persist in certain kinds of suboptimal practices for far too long; I’m often loath to steal time from a current task to thrash out a solution to something that is bothering me at the fringes. Eventually I snapped and asked my colleagues what they used to satisfy their API reference needs when working with Rails. I was dismayed when I was told they used the same strategy as mine. There had to be something a little less primitive.
Enter the Rails Searchable API Doc
A few weeks ago I was directed to the Rails Searchable API Doc beta by Vladimir Kolesnikov: a nicely bundled, offline, HTML Rails API reference with full search facilities. Simply download a bundle (Rails, Ruby and gem documentation bundles are available) and unpack in a convenient location. Open the index.html file and voila! You now have a nice and fast Rails API reference available offline. The only problem with this is that a web browser is a very ad-hoc environment. I often have scores of tabs open, browsing random resources around the web. This meant that I now had the problem of trying to find my current Rails documentation amidst all of the other random guff that builds up in my browser.
Fluid is a Mac OS X application that enables the configuration of site-specific browsers. An SSB can essentially make a web application appear much like a first-class desktop application via a dedicated web browser sandbox. An SSB is a great way to keep your Google Reader, Facebook or other web sessions completely separate from each other, hosted in separate processes complete with individual Dock icons. It also turns out to be a really handy way of keeping HTML based references close at hand.
- Grab Fluid and the Rails Searchable API.
- Snag a nice Ruby on Rails icon. This is to be used for the Dock.
- Unpack all of these bundles into appropriate places.
- Launch Fluid and set up a Rails API site-specific browser.
- Consider dragging the generated SSB to the Dock.
Fluid uses WebKit as its rendering engine, and configuration of the browser is naturally very similar to Safari. By default it maximizes browsing area by eliminating the tool and status bars but these can be added via the menu. In the screen shot you can see I’ve added back, forward and font resizing buttons. For a documentation SSB, it also makes sense to set Fluid to only hide the window when the window is closed. Such a setting is available in the Behaviour tab of the application preferences.
For those with open source cravings, Mozilla Labs has an SSB project called Prism that offers similar functionality, although I find their offering a little more sparse.