June 20, 2023

Offline Ruby and Rails documentation

The vacation season is starting, and it can be helpful to have access without the internet to the documentation of Ruby, Rails, and the gems you use. If you are going on a trip and taking your laptop, you can prepare them in advance by following this little guide.

Let’s start with Ruby, that’s the easiest. To browse the API documentation offline, you can download a prebuilt copy from https://ruby-doc.org/downloads/. Extract the downloaded archive, open index.html and you can browse the documentation.

For Rails, you can generate the Rails Guides for local browsing. You need to clone the Rails repository, install some dependencies and run a rake command to generate the guides:

[~/] git clone https://github.com/rails/rails.git
[~/] cd rails/guides
[~/rails/guides] bundle
[~/rails/guides] rake guides:generate:html

When it is done, you will have the files in the output directory. The above will generate the guides for edge Rails, if you want to see the guides for a specific version, you need to checkout that branch. For instance for Rails 7.0:

[~/rails/guides] git checkout 7-0-stable
[~/rails/guides] rake guides:generate:html

You would probably also want to have the API documentation at hand. To generate that, you need to run the following rake command:

[~/rails] rake rdoc

Then open doc/rdoc/index.html in a browser.

For the gems, you have multiple options:

RDoc

First of all, you should make sure you have the rdoc files generated for the gems you have installed on your system. For that you can run:

gem rdoc --all

Once the docs are generated, you need to install the rubygems-server gem and start the server:

gem install rubygems-server
gem server

YARD

YARD is another documentation tool for ruby gem. To run the yard server, you need to install the gem and start the server:

gem install yard
yard gems

RI

If you don’t want to leave your terminal, you can also use ri to browse the documentation. You can run ri Array to view the documentation of the Array class, or ri ActionController::Base to view the rdoc docs for ActionController::Base.

That’s it for the week!