How to create local copy of Rails API doc and Guides

35 Flares 35 Flares ×

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.

API Doc

rake rdoc

You might want to prefix bundle exec 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.

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:

gem 'RedCloth'

Now, we need to run a bundle install.

Once that is completed, run the following command :

rake doc:guides

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:

cd ..
rm -rf rails
   
rvm gemset delete railsdocs

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.

This entry was posted in Ruby on Rails and tagged , , , , . Bookmark the permalink.

About me

Hello, there! I'm Aslam Najeebdeen, a web craftsman, a visionary, a Rubyist and founder of frontcube
  • Anonymous

    Thank you for you post.

    I have built my own api doc successful. but when I want to create guides with command “bundle exec rake doc:guides”, I got this: Don’t know how to build task ‘doc:guides’Could you kind to give me more details about generate rails guides?

    • http://mohamedaslam.com Aslam

      Hey, Thanks for your comment.

      In order to generate Rails guides, you should create a new Rails project. It’s my mistake. I’ve updated the post.

      Cheers!

  • Adam Bardsley

    Very useful but two things
    gem ‘RedCloth’should begem install ‘RedCloth’

    and if you don’t have rdoc 2.4.3 u need
    gem install rdoc –version=2.4.3

  • sf

    Great post. I’m having problems with:
    rake doc:guidesCould not find gem ‘rails (= 4.0.0.beta) ruby’ in any of the gem sources listed in your Gemfile.Run `bundle install` to install missing gems.

    bundle install gives the same message.

    When I do a bundle exec rake doc:guides I get the same thing. Any ideas? I think I followed the tutorial verbatim. Thanks!

    • http://mohamedaslam.com Aslam

      Can I see your Gemfile?

    • Mike

      I think you’d want to checkout a specific branch, otherwise you’ll be trying to bundle gems in the HEAD which is currently 4.0. 

      So you’d want to do a `git checkout v3.1.3`.  To see a list of the tagged releases, just do a `git tag`. 

  • Anonymous

    you can also create documentation for your ruby sources. install Vladimir Kolesnikov’s “sdoc” gem, than “cd ~/.rvm/src/ruby-1.9.3-p0/” or another ruby of your choice, than rub “sdoc –op ~/where/to/put/documentation”

    you can also merge ruby and rails documentation (very useful with activesupport core classes extensions) with sdoc-merge utility from the same gem

  • Jeroen van Ingen

    I got the error ‘no such file to load – sdoc’. Even if I install the gem using ‘gem install sdoc’
    Anyone know how to fix this?

  • Marcel

    I ran into this error from rdoc:
    ambiguous option: -e

    The problem was that I was running ruby 1.8.7 and rdoc only accepts this option under 1.9.  It only advertises it with “rdoc –help” under 1.9 also.

    Then under ruby 1.9.2, I encountered:
    in `normalize_yaml_input': invalid byte sequence in US-ASCII

    I resolved by setting LANG=en_US.UTF-8 in my environment.

  • Jonathan

    How would I create an SDOC like this for the Ruby Core and Ruby Standard Library?

    • http://mohamedaslam.com Aslam

      Navigate to the Ruby installation directory via terminal,

      Ex: “cd ~/.rvm/src/ruby-1.9.3-p0/” 

      then run “sdoc –op ~/where/to/put/documentation”

      For more information, checkout sdoc GitHub page: https://github.com/voloko/sdoc

  • Wahid Lahlou

    Very nice article, thank you!

  • Arno.Nyhm

    there is an app for this: Dash ( see http://kapeli.com/ )

  • shacker

    Hmm, after following these steps I just get:

    $ bundle exec rake rdoc
    rake aborted!
    Don’t know how to build task ‘rdoc

    Ideas?

  • Warren Spence

    Really a nice post! Thanks for share…..
    WRS Builder

  • lsiden

    Thank you for the excellent post Rajib. A week or so ago, I stumbled on a command that will open a browser window and display the rdocs for a Ruby class object or method. I think it had the keyword “show” or “open” in it. Now I can’t for the life of me find it again, even with Google. I looked at all the standard rake targets (rake -T), gem command options, and even rails, but can’t find it anywhere. Do you know how to do this?

35 Flares Twitter 30 Facebook 5 Google+ 0 Email -- 35 Flares ×