Offline Gem Server
July 8th, 2009I’ve had an offline gem documentation server installed for a while on my machine, after following Jason Seifer’s instructions.
Recently, however, when I installed new gems I got the following error:
invalid argument: –fmt=html
This is, I think, because the hanna gem that provides the rdoc template needs to use a html output formatter, which seems to have disappeared from newer versions of rdoc.
As a solution, I’ve switched to the sdoc gem, which I think has a better rdoc template than hanna.
The full install instructions for my offline gem documentation server are:
- Install pre-requisites: Apache and Phusion Passenger – also add gems.github.com to your gem sources
- Install sdoc gem – this provides the rdoc template, that puts a search box on each rdoc page to allow you to search the methods and classes of a gem:
sudo gem install voloko-sdoc
- Edit your ~/.gemrc file, to add the correct options for sdoc, and (optionally) stop ri docs being generated:
gem: --no-ri rdoc: --inline-source --line-numbers --fmt=shtml --template=direct
- Regenerate all your rdocs so they all use the new sdoc template:
sudo gem rdoc --all --no-ri
- Install the sinatra-rubygems gem, to allow your gem rdocs to be served by passenger installed on your local machine:
sudo gem install jnewland-sinatra-rubygems
- Add the following to your /etc/hosts file:
127.0.0.1 gems.local
- Add the following to your apache passenger config – customizing the DocumentRoot and Log locations as required:
<VirtualHost *:80> DocumentRoot "/opt/sinatra-rubygems/public" ServerName gems.local:80 ErrorLog /var/log/apache2/gems-error_log CustomLog /var/log/apache2/gems-access_log common </VirtualHost>
- After restarting apache, you should then be able to visit gems.local