Reading Documentation for Installed Gems

Table of contents:

Problem

You want to read the RDoc documentation for the gems you have installed. Although some gem projects provide human-written documentation like tutorials, the generated RDoc documentation isn usually available online.

Solution

RDoc documentation isn usually available online because when you install a gem, Ruby generates your very own HTML copy of the RDoc documentation and installs it along with the software. The documentation you need is probably already on your computer.

The simplest way to browse the documentation for your installed gems is to run the gem_server command, then visit http://localhost:8808/. Youll see all your installed gems in a table form, and be able to browse the generated documentation of each gem that provides any.

Otherwise, you can find your Rubygems documentation directory, and browse the installed documentation with local filesystem tools.

Discussion

The generated rdoc for a gem is kept in the doc/ subdirectory of the base directory in which the gem was installed. For instance, on my computer, gems are installed in /usr/lib/ruby/gems/1.8/. For every gem that has RDoc, the generated HTML documentation will be kept in the directory /usr/lib/ruby/gems/1.8/doc/[gem name]/rdoc/. If I were to install one particular gem to another directory, the documentation for the gem would be in a doc/ subdirectory of that directory.

Heres some code that prints out the location of the RDoc files for every installed gem. Unless youve installed specific gems in nonstandard locations, theyll all be in the doc/ subdirectory of Gem.dir. This code snippet also shows off some of the capabilities of Gem::DocManager, the Ruby class you can use to manipulate a gems RDoc.

	require 
ubygems
	Gem.manage_gems

	def show_gem_rdoc
	 puts "Your generated docs are all probably in #{File.join(Gem.dir, "doc")}"

	 puts "Just to be safe, Ill print out every gems RDoc location:"
	 specifications_dir = File.join(Gem.dir, specifications)
	 lacking_rdoc = []
	 Gem::SourceIndex.from_installed_gems(specifications_dir).each do |path, spec|
	 manager = Gem::DocManager.new(spec)
	 if manager.rdoc_installed?
	 doc_path = File.join(spec.installation_path, doc, spec.full_name)
	 puts " #{spec.full_name} => #{doc_path}"
	 else
	 lacking_rdoc << spec.full_name
	 end
	 end

	 unless lacking_rdoc.empty?
	 puts "
These installed gems have no RDoc installed:"
	 puts " #{lacking_rdoc.join("
 ")}"
	 end
	end

	show_gem_rdoc
	# Your generated RDoc is probably all in /usr/lib/ruby/gems/1.8/doc
	# Just to be safe, Ill print out every gems RDoc location:
	# flexmock-0.1.7 => /usr/lib/ruby/gems/1.8/doc/flexmock-0.1.7
	# simple-rss-1.1 => /usr/lib/ruby/gems/1.8/doc/simple-rss-1.1
	# classifier-1.3.0 => /usr/lib/ruby/gems/1.8/doc/classifier-1.3.0
	# actionmailer-1.1.5 => /usr/lib/ruby/gems/1.8/doc/actionmailer-1.1.5
	# …
	#
	# These installed gems have no RDoc installed:
	# Ruby-MemCache-0.0.1
	# RedCloth-3.0.4
	# sources-0.0.1
	# …

RDoc is generated for most gems whether or not the author was careful to add RDoc descriptions to all their Ruby code. At minimum, a gems RDoc will list the classes and methods present in the gem, which is useful in a bare-bones way.

If you don want to generate RDoc when you install a gem, pass in the --no-rdoc argument to the gem install command. The only real reason to do this is a concern for disk space.

The flip side of reading a gems documentation is writing it. When you e writing your gemspec (see Recipe 18.6), you should set spec.has_rdoc = true. This will let the end users gem installer know that your gem was written with RDoc in mind. It doesn do much except suppress a warning during the installation of your gem.

Problem

Solution

Discussion

See Also