Automatically Generating Documentation

Credit: Stefan Lang


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


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

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

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.


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, 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:


Updates the HTML documentation by running RDoc.


Removes the directory and its contents created by the rdoc task.


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.

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

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

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 => [

Available attributes

Heres a list of attributes that can be set in the block given to


Name of the directory where the produced HTML files go. Defaults to html.


A title for the produced HTML pages.


Name of the input file whose contents should appear at the initial page of the HTML output.


Name of the template to be used by RDoc.


Initialized to an empty filelist. Just call the include method with the names of files to be documented, or glob patterns matching multiple files.


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.

See Also

  • Recipe 19.3, "Cleaning Up Generated Files"
  • Recipe 19.8, "A Generic Project Rakefile"
  • The RDoc documentation for the Rake::RDocTask class (



Date and Time



Files and Directories

Code Blocks and Iteration

Objects and Classes8

Modules and Namespaces

Reflection and Metaprogramming


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 © 2008-2020.
If you may any questions please contact us: