Rails: Creating a local copy of the API Documentation

RubyOnRailsThis is an excellent tip to know, for me at-least, as I get back into the mix of using Rails for Web Development. Recently, I just purchased Agile Web Development with Rails 2nd ed., and plan on reading the whole book front to back. Yes, that’s right! Front-to-back. I purchased the first edition last year, but got halfway through, only to be distracted by administering *Nix and Windows! 😦

Anyway, having a local copy of the Rails API Documentation is very valuable, especially when you are on the road and there is no Internet! It took me 5 minutes and 36 seconds to create my own rails API locally.

1. Create a fake rails application directory — RailsDoc

swinful@thinkpad> cd Desktop
swinful@thinkpad> rails RailsDoc
create app/controllers
create app/helpers
create app/models
create app/views/layouts
create log/server.log
create log/production.log
create log/development.log
create log/test.log

2. Freeze the application — RailsDoc

swinful@thinkpad> cd RailsDoc/
swinful@thinkpad> rake rails:freeze:gems
(in /usr/home/swinful/Desktop/RailsDoc)
Freezing to the gems for Rails 1.2.2
rm -rf vendor/rails
mkdir -p vendor/rails
cd vendor/rails

The freeze command will essentially make it possible to use the version of rails and gems that were used while the application was being developed, but at a later time. The next step will take the most time:)

3. Rake, one last time — RailsDoc

swinful@thinkpad> echo >! vendor/rails/activesupport/README
swinful@thinkpad> rake doc:rails
(in /usr/home/swinful/Desktop/RailsDoc)
rm -r doc/api

xmlmarkup.rb: mc………….
Generating HTML…

Files: 263
Classes: 417
Modules: 525
Methods: 1933
Elapsed: 337.176s
69.724u 45.620s 5:37.66 34.1% 5+57932k 67+8io 3pf+0w

In the RailsDoc folder, move doc/api to another directory.

swinful@thinkpad> mv doc/api ~/Desktop/RailsApi

That’s all.

This entry was posted in Rails. Bookmark the permalink.

8 Responses to Rails: Creating a local copy of the API Documentation

  1. ant21 says:

    Really thanks for your awesome method. There is no local rdoc for rails through gem_server on my ubuntu box. I don’t know why.

  2. Julien says:

    Very useful, thanks !

  3. Albert says:

    Thanks, it helps especially when rubyonrails.org was down.

  4. swinful says:

    Hi Julien, I am glad to hear you found this posting useful.


  5. Andrew says:

    Hahaha =D
    All you need is to copy the “doc” folder with all these htmls from rubygems directory to your desktop (or create a link).
    On openSUSE they are located in /usr/lib/ruby/gems/1.8/doc/rails-2.3.8/

  6. swinful says:

    @Andrew: Some linux distros may already have the local copy of the API Documentation as you point out with openSUSE. But for those that do not, knowing how to generate the docs, especially when no internet access is available, can come in handy. -:)

    Thank you for sharing your shortcut. -:)


  7. Andrew says:

    No =)
    No matter which distro u are using, rubygem content should not vary unless you are using something really very exotic (do u?=)).
    Most distros don’t include recent rails at all, but it is ok, because the standard way to install rails is rubygems (gem install rails or gem1.8 install rails). Docs will be in the *somefolder*/lib/ruby/gems/1.8/doc/rails-*version*.
    You can find out where your gems are located with ‘gem (or gem1.8) help install’, somewhere at the end of the help message.
    And if you prefer APT (in case u are an Ubuntu fan=), it should still install the same files as with gems. But remember the version in Ubuntu repos is outdated. openSUSE is the only distro I know which ships recent versions of popular rubygems through the SUSE’s packaging system.

    Your solution is still useful because it points at how to create local copy of Rails Guides =)
    BTW, rake doc:guides πŸ˜‰
    and, sorry for my english. 99,9% of my time i speak russian.

  8. Andrew says:

    Well, you were right, api docs are not included with rails gem. I’m sorry. Rails is the only gem I know with empty docs folder.
    But you can still use my solution to read specs for any other gem.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s