Reading Documentation for Installed Gems






Reading Documentation for Installed Gems

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't usually available online.

Solution

RDoc documentation isn't 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/. You'll 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.

Here's some code that prints out the location of the RDoc files for every installed gem. Unless you've installed specific gems in nonstandard locations, they'll 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 gem's RDoc.

	require 'rubygems'
	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, I'll print out every gem's 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 "\nThese installed gems have no RDoc installed:"
	    puts " #{lacking_rdoc.join("\n ")}"
	  end
	end

	show_gem_rdoc
	# Your generated RDoc is probably all in /usr/lib/ruby/gems/1.8/doc
	# Just to be safe, I'll print out every gem's 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 gem's RDoc will list the classes and methods present in the gem, which is useful in a bare-bones way.

If you don't 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 gem's documentation is writing it. When you're writing your gemspec (see Recipe 18.6), you should set spec.has_rdoc = true. This will let the end user's gem installer know that your gem was written with RDoc in mind. It doesn't do much except suppress a warning during the installation of your gem.

See Also

  • The Ruby Standard Library Documentation collection (http://www.ruby-doc.org/stdlib/) contains generated HTML for the RDoc of all the packages in the Ruby standard library: it includes everything in lib/ruby/, but it doesn't include the core application

  • Recipe 17.11, "Documenting Your Application"

  • Recipe 18.6, " Packaging Your Code as a Gem"

  • Recipe 19.2, "Automatically Generating Documentation"



 Python   SQL   Java   php   Perl 
 game development   web development   internet   *nix   graphics   hardware 
 telecommunications   C++ 
 Flash   Active Directory   Windows