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:
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:
rvm use --create ruby-1.9.2-p290@railsdoc
Either way you’ll need to install sdoc.
sudo gem install sdoc
Step 1 – Download sources
git clone https://github.com/rails/rails.git
git clone https://github.com/ruby/ruby.git
Step 2a – Generate ruby docs
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.
git co v1_9_2_290
sdoc -o doc/ruby ruby
cd ..
Step 2b – Generate rails docs
Repeat for the rails doc. Here I’m documenting rails version 3.2.0.
cd rails
git co v3.2.0
sdoc --fmt=sdoc -g -o doc/rails -A rails
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.
sdoc-merge --title "Ruby 1.9.2-p290 and Rails 3.2.0" --op merged --names "Ruby,Rails" doc/ruby 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:
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