Undoubtedly, we software developers spend a good portion of our time reading documentation, often online. Recently, I have been traveling a lot and although I have my mobile phone set up for tethering, the internet connection is very fragile at times. Waiting for pages to load forever is not really fun, so I needed a way to access the most important Ruby and Rails documentation offline. Since there are quite a few steps involved in setting this up, I thought I’d share it and hope it will be useful for others as well.
Please be aware that this guide is written for OS X users; if you use a different operating system, you will need to adjust the steps accordingly.
Pow lets you start a local server that serves apps under a local url like
http://app-name.dev. This makes it convenient to access the documentation we
will set up below and frees you from need to keep servers running on
localhost with meaningless port numbers that noone can remember. You can install
For more information, visit pow.cx. I recommend using Pow
in conjunction with the
which provides a convenience wrapper around the bare shell commands that are
used to manage up Pow apps. The most important command we will use is
powder link [APP_NAME], which sets up your app to be served locally by Pow. You can
powder from Rubygems via
Ruby Core Documentation
Pre-rendered Ruby core documentation is available from ruby-doc.org. To serve it locally via Pow, you can do:
Your Ruby documentation is now available at http://ruby-doc.dev. Of course, adjust the version number to your needs and/or download multiple versions.
Save the following file as
~/Library/LaunchAgents/YardDocs.plist and adjust
the path to the
yard executable as needed.
Next, start the server and set up Pow to do the port forwarding.
Your Ruby documentation is now available at http://gem-doc.dev. If you are missing some gems in the list or have disabled documentation generation to speed up Bundler as I did, you can regenerate all Gem documentations with the following command:
Rails API Documentation
Rails documentation can be generated directly from a Rails app, so the first step is to make a minimal Rails app that will serve the only purpose of displaying documentation.
First, add the
rails gem in the desired version to your
Gemfile. You will also need the
nokogiri gems to generate the documentation, so go ahead and add
these as well.
Then, install all the Gems with
Rails expects an application to be present before it lets you run the Rake task to generate
the documentation. You can fake an entire Rails application directly in the
Rakefile like this:
Now, you have Rails’ Rake tasks at your disposal and are able to generate the documentation:
To serve the documentation with Pow, you need to add a Rackup file at
and finally you can serve it via Pow:
To read the Rails Guides locally, you can simply clone the folder that you have created for the Rails API Documentation.
This time, you need to run a different Rake task to generate the guides:
Since the guides end up in a different directory than the API documentation, you will need to adjust the location specified in the Rackup file as well:
Finally, you can set up Pow to serve the Rails Guides: