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.
rvm gemset create railsdocs
rvm gemset use railsdocs
Note that If you don’t have bundler gem in your global gem set, you need to install it first using the below command:
gem install bundler
The next step is to clone the Rails git repository to your local machine as follows:
git clone http://github.com/rails/rails.git
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.
bundle install –without db
Now we are all set. Let’s proceed with generating the docs.
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.
In order to generate the Rails Guides, we need create a new rails project.
rails new railsguides
Rails Guides depends on an additional RubyGem called RedCloth to Gemfile. So our next step is to add this to the Gemfile:
Now, we need to run a bundle install.
Once that is completed, run the following command :
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:
rm -rf rails
rvm gemset delete railsdocs
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.
I’m glad that finally, his efforts paid off and was integrated into the actual Rails API documentation.