Automatically Generating Documentation

Table of contents:

Credit: Stefan Lang

Problem

You want to automatically create HTML pages from the RDoc formatted comments in your code, and from other RDoc formatted files.

Solution

Within your Rakefile, require the rake/rdoctask library and create a new Rake:: RDocTask. Heres a typical example:

	require 
ake/rdoctask

	Rake::RDocTask.new(
doc) do |t|
	 t.rdoc_files.include(README, lib/**/*.rb)
	 t.main = README
	 t.title = "MyLib API documentation"
	end

Now you can run the command rake rdoc from a shell in your projects top-level directory. This particular Rake task creates API documentation for all files under the lib directory (and its subdirectories) whose names end in .rb. Additionally, the RDoc-formatted contents of the top-level README file will appear on the front page of the documentation.

The HTML output files are written under your projects %(filename)html% directory. To read the documentation, point your browser to %(filename)html/index.html%. The browser will show "MyLib API documentation" (that is, the value of the tasks title) as the page title.

Discussion

It is common practice among authors of Ruby libraries to document a librarys API with RDoc-formatted text. Since Ruby 1.8.1, a standard Ruby installation contains the rdoc tool, which extracts the RDoc comments from source code and creates nicely formatted HTML pages.

Unlike the tasks you define from scratch with the task method, but like the TestTask covered in Recipe 19.1, Rake::RDocTask.new takes a code block, which is executed immediately at task definition time. The code block lets you customize how your RDoc documentation should look. After running your code block, the Rake:: RDocTask object defines three new Rake tasks:

rdoc: Updates the HTML documentation by running RDoc.
clobber_rdoc: Removes the directory and its contents created by the rdoc task.
rerdoc: Force a rebuild of the HTML-documentation. Has the same effect as running clobber_rdoc followed by rdoc.

Now we know enough to integrate the Rake::RDocTask into a more useful Rakefile. Suppose we want a task that uploads the documentation to RubyForge (or another site), and a general cleanup task that removes the generated HTML-documentation as well as all backup files in the project directory. To keep the example simple, Ive inserted comments instead of the actual commands for uploading and removing the files; see Recipes 19.3 and 19.8 for more realistic examples.

	require 
ake/rdoctask

	Rake::RDocTask.new(
doc) do |t|
	 t.rdoc_files.include(README, lib/**/*.rb)
	 t.main = README
	 t.title = "MyLib API documentation"
	end

	desc Upload documentation to RubyForge.
	task upload => 
doc do
	 # command(s) to upload html/ and contents to RubyForge
	end
	desc Remove generated and backup files.
	task clobber => clobber_rdoc do
	 # command(s) to remove all files ending in ~ or .bak
	end

Finally, we make the default task dependent on the rdoc task, so that RDoc gets built automatically when you invoke rake with no task. If there already is a default task, this code will simply add another dependency to the existing task:

	task :default => [
doc]

Available attributes

Heres a list of attributes that can be set in the block given to Rake::RDocTask.new.

rdoc_dir: Name of the directory where the produced HTML files go. Defaults to html.
title: A title for the produced HTML pages.
main: Name of the input file whose contents should appear at the initial page of the HTML output.
template: Name of the template to be used by RDoc.
rdoc_files: Initialized to an empty filelist. Just call the include method with the names of files to be documented, or glob patterns matching multiple files.
options: An array of arguments to be passed directly to rdoc. Use this if none of the other attributes fits your needs. Run rdoc --help for a list of available options.

Problem

Solution

Discussion

Available attributes

See Also