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:
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.
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:
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.
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]
Heres a list of attributes that can be set in the block given to Rake::RDocTask.new.
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.
Date and Time
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
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
Extending Ruby with Other Languages