Create Local Ruby on Rails Documentation for Offline Use

Having your own local version of Ruby on Rails documentation has its benefits, including offline use, merged documentation for Ruby and Rails, and having docs for the exact versions that your current project uses.

Creating them is pretty simple thanks to the sdoc gem.

Create a docs directory and install sdoc

Create a home for your Ruby and Rails docs:

1
2

mkdir railsdoc  
cd railsdoc

sdoc provides all the magic to generate searchable ruby docs in HTML.  So the first thing to do is to install the sdoc gem.  I use RVM, so I created its own gemspec with a .rvmrc file:

1

rvm use –create ruby-1.9.2-p290@railsdoc

Either way you’ll need to install sdoc.

1

sudo gem install sdoc

Step 1 – Download sources

1
2

git clone https://github.com/rails/rails.git  
git clone https://github.com/ruby/ruby.git

Step 2a – Generate ruby docs

1

cd ruby

Now here you have to decide what version of ruby you want to document.  Using git, checkout the version / tag you want.  (In the following example, I switching to ruby version 1.9.2-p290)  Then have sdoc create the docs.

1
2
3
4

git pull --tags
git co v1_9_3_547  
sdoc -o doc/ruby ruby --exclude="test/*.rb" --exclude="fixtures" --exclude="ci" --exclude="tasks" --exclude="tools" --exclude="Gemfile" --exclude="Gemfile.lock" --exclude="CHANGELOG*" --exclude="MIT-LICENSE" --exclude=".*rdoc" --exclude=".*gemspec" --exclude="Rakefile" --exclude="bin/*" --exclude="version.rb" --exclude="spec" --exclude="tool" --exclude="win32" --exclude="template" --exclude="sample"  --exclude="bcc32" --exclude="benchmark" --exclude="bootstraptest" --exclude="doc" ---exclude="man" --exclude="cygwin"
cd ..

Step 2b – Generate rails docs

Repeat for the rails doc.  Here I’m documenting rails version 3.2.0.

1
2
3
4

cd rails  
git co v3.2.18
sdoc -f sdoc -g -o doc/rails -A rails --exclude="test/*.rb" --exclude="fixtures" --exclude="ci" --exclude="tasks" --exclude="tools" --exclude="Gemfile" --exclude="Gemfile.lock" --exclude="CHANGELOG*" --exclude="MIT-LICENSE" --exclude=".*rdoc" --exclude=".*gemspec" --exclude="Rakefile" --exclude="bin/*" --exclude="version.rb"
cd ..

Step 3 – Merge Rails Docs

Now that we’ve generated our ruby docs and rails docs, now its time to merge them into on directory.  sdoc provides a command to merge them.

I would change the title of the command below to reflect what versions of ruby and rails you have.

1

sdoc-merge -t "Ruby 1.9.3-p547 and Rails 3.2.18" -o merged -n "Ruby,Rails" ruby/doc/ruby rails/doc/rails

Done

That’s it folks.

Point your browser to “merged/index.html” and rejoice in your merged, local, and searchable Ruby on Rails docs!

If you’re osx you can run the following to open it up:

1
2

open merged/index.html

Updating

With your railsdoc directory, you can easily update the docs by:

• Updating the git repos (git fetch origin)
• Checking out the new version you want to document (git co vXYZ)
• Repeat Steps 2a, 2b and 3