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 |
|
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
|
|
Either way you’ll need to install sdoc.
1
|
|
Step 1 – Download sources
1 2 |
|
Step 2a – Generate ruby docs
1
|
|
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 |
|
Step 2b – Generate rails docs
Repeat for the rails doc. Here I’m documenting rails version 3.2.0.
1 2 3 4 |
|
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
|
|
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 |
|
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