Vladimir's Tech Blog

Browse Ruby documentation with improved gem server

July 21, 2008

Firefox screenshot I am currently using Netbeans as my Ruby IDE. The autocompletion feature provides some RDoc snippets but does not always work.

The second option is to use some web resources like http://ruby-doc.org/ or directly use google. But this obviously does not work offline and possibly provides the wrong version of the documentation for those living on the bleading edge. For example, I use the "nightly" RSpec version installing it directly from the git hub.

So I stuck to the local gem server. Unfortunately it's start page is not so convenient, so I've patched the rubygems/server.rb. You can append following near the end of file:

# extended by Vladimir Dobriakov, http://www.innoq.com/blog/vd/
rdoc_proc = lambda do |req, resp|
    gem_name = req.query['gem']
    found_gems = Dir.glob("#{@gemdir}/doc/#{gem_name}*")
    if found_gems.length == 1
        new_path = File.basename(found_gems[0])
        resp.status = 302
        resp['Location'] = "/doc_root/#{new_path}/rdoc/index.html"
    else
        found_gems = Dir.glob("#{@gemdir}/doc/*") if found_gems.empty?
        resp.body = '<ul>'
        found_gems.each do |gem_name|
            path = File.basename(gem_name)
            url = "/doc_root/#{path}/rdoc/index.html"
            resp.body << "<li style='margin-top: 1em'><a href='#{url}'>#{path}</a></li>"
        end
        resp.body << '</ul>'
        resp['Content-Type'] = 'text/html'
    end
end
@server.mount('/rdoc', WEBrick::HTTPServlet::ProcHandler.new(rdoc_proc))

just before

    trap("INT") { @server.shutdown; exit! }
    trap("TERM") { @server.shutdown; exit! }

    @server.start
  end
end

Now the new code is tied to urls like http://localhost:3333/rdoc?gem=active providing either a list of the links to the documentation for the gems, which names start with 'active' or directly jumping to the rdoc of the gem in case there is only one search hit.

In my del.icio.us Plugin for the Firefox I connected http://localhost:3333/rdoc?gem=%s to rdoc keyword. So now I can simply type in something like rdoc httpauth

UPDATE. One additional trick. Run

# please adjust paths accordingly
# use for example 'locate yaml.rb' and 'gem environment'
# for identifying directories

# install ruby sources
cd /usr/src
sudo apt-get source ruby

rdoc -o /usr/lib/ruby/gems/1.8/doc/core/rdoc /usr/lib/ruby/1.8 ruby1.8-1.8.7.72

to generate the rdoc for the core ruby libraries (not gems). The -o parameter specifies the output directory. Two directory names, that follow, specify the ruby- and the C sources respectively.

And how do you browse the ruby documentation?

Vladimir's Tech Blog

Browse Ruby documentation with improved gem server

Comments

Post a comment