Question

How do I include a ruby code file, as is, into RDoc?

I have an example.rb file that documents how to use my gem and I would like to include that as one of the files like the README.rdoc and HISTORY.rdoc.

I’ve already figured out how to convert the ruby source code into HTML using the Syntax gem but I can’t figure out how to make RDoc include the file without parsing it.

When I tell RDoc to include the html file it isn’t listed and if I fake it out by using rdoc or txt as the file extension it doesn’t display properly (the file is still actually html).

I’ve got a solution that works it’s just incredibly ugly. There has got to be a better way to do this that’s native to rdoc but I don’t see it.

Here’s what I have in my Rakefile:

# Build rdocs
require 'rake/rdoctask'
require 'syntax/convertors/html'
rdoc_dir = 'rdoc'
# This is rdoc1 but it doesn't work unless you DON'T wrap it in a task
# Generate html files from example ruby files
convertor = Syntax::Convertors::HTML.for_syntax "ruby"
replacement_key = "REPLACE_THIS_TEXT_WITH_PROPER_HTML"
# Create dummy files
Dir.glob('examples/*.rb').each do |file|
  File.open("#{file}.txt", "w") do |dummy_file|
    dummy_file.write(replacement_key)
  end
end

# Call the rdoc task
Rake::RDocTask.new(:rdoc2) do |rdoc|
  rdoc.rdoc_dir = rdoc_dir
  rdoc.title = "pickled_optparse #{version}"
  rdoc.rdoc_files.include('README*')
  rdoc.rdoc_files.include('HISTORY*')
  rdoc.rdoc_files.include('examples/*.txt')
  rdoc.rdoc_files.include('lib/**/*.rb')
end

task :rdoc3 do
  # Now use a hammer to replace the dummy text with the
  # html we want to use in our ruby example code file.
  html_header = File.read('rake_reqs/html_header.html')
  Dir.glob('examples/*.rb').each do |file|
    html_ruby = convertor.convert(File.read(file))
    rdoc_file = "#{rdoc_dir}/examples/#{File.basename(file,".rb")}_rb_txt.html"
    fixed_html = File.read(rdoc_file).gsub!(replacement_key, "#{html_header}#{html_ruby}")
    File.open(rdoc_file, "w") {|f| f.write(fixed_html)}
    File.delete("#{file}.txt")
  end
end

task :rdoc => [:rdoc2, :rdoc3]

Answer 1

Sorry I can’t give you an actual answer but I’m looking at sdoc myself.
You can install the gem from ruby gems.