Automatically Generating Documentation

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.

See Also

Related

Категории