How to create local copy of Rails API doc and Guides

If you’re a programmer, I’m sure you know the importance of API documentation. No matter what language you’re using, or what your expertise level is, API documentation is always essential for your reference, whenever you need it. Of course you can find and use API documentations online, but I’m sure there are many occasions, when you’ve wished to have an offline version of the document. For instance when you face connectivity problems or network issues and you just can’t get online, or even while traveling in airplanes, as we know, internet accessibility is not always possible.

Due to these reasons, I personally prefer to have a local version of the API documentation and I believe that many of you would also find it useful. Let me show you how you can also generate your own copy of the Rails API as well as the Guides.

First of all, If you’re using RVM or rbenv to manage your Rubies, it is always a good idea to create an isolated gem set for this task. As for me, I’m using RVM here. For those who are not using any of these, you can simply skip these steps.

[cc lang=”bash”]
rvm gemset create railsdocs

rvm gemset use railsdocs
[/cc]

Note that If you don’t have bundler gem in your global gem set, you need to install it first using the below command:

[cc lang=”bash”]
gem install bundler
[/cc]

The next step is to clone the Rails git repository to your local machine as follows:

[cc lang=”bash”]
git clone http://github.com/rails/rails.git
[/cc]

One thing you might want to note is that when we run the rake tasks, it will check against the Gemfile to make sure that all the necessary RubyGems are available. So we’d better install all necessary RubyGems as well. At this point we can omit the database gems, as we only need the supportive RubyGems to generate the API doc.

[cc lang=”bash”]
bundle install –without db
[/cc]

Now we are all set. Let’s proceed with generating the docs.

API Doc

[cc lang=”bash”]
rake rdoc
[/cc]

You might want to prefix [cci lang=”bash”]bundle exec[/cci] to above command if you run in to any problem running rake. This command will generate the API doc under the doc folder.

Rails Guides

In order to generate the Rails Guides, we need create a new rails project.

[cc lang=”bash”]
rails new railsguides
[/cc]

Rails Guides depends on an additional RubyGem called RedCloth to Gemfile. So our next step is to add this to the Gemfile:

[cc lang=”ruby”]
gem ‘RedCloth’
[/cc]

Now, we need to run a bundle install.

Once that is completed, run the following command :

[cc lang=”bash”]
rake doc:guides
[/cc]

This will also generate the RailsGuide under the doc folder.

You have the option to move these two folders to a more accessible location in your hard drive.

Finally, you can get rid of the rails repo as well as the gem set, if you don’t require them any longer, using the following commands:

[cc lang=”bash”]
cd ..
rm -rf rails

rvm gemset delete railsdocs
[/cc]

YARD

If you are a fan of YARD docs, you might find this post is very useful written by my friend Michael de Silva (aka bsodmike).

Special credit

As far as API documentations are concerned, I’m sure you wouldn’t disagree with me that most of them are intimidating. It usually takes some time and effort to get what we really need. Well, the Rails API doc is no exception. Fortunately, someone by the name of Vladimir Kolesnikov actually recreated the Rails API doc into a very user friendly manner.

Rails API - new UI

I’m glad that finally, his efforts paid off and was integrated into the actual Rails API documentation.