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 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.

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 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"


Strings

Numbers

Date and Time

Arrays

Hashes

Files and Directories

Code Blocks and Iteration

Objects and Classes8

Modules and Namespaces

Reflection and Metaprogramming

XML and HTML

Graphics and Other File Formats

Databases and Persistence

Internet Services

Web Development Ruby on Rails

Web Services and Distributed Programming

Testing, Debugging, Optimizing, and Documenting

Packaging and Distributing Software

Automating Tasks with Rake

Multitasking and Multithreading

User Interface

Extending Ruby with Other Languages

System Administration



Ruby Cookbook
Ruby Cookbook (Cookbooks (OReilly))
ISBN: 0596523696
EAN: 2147483647
Year: N/A
Pages: 399

Similar book on Amazon

Flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net