Syntax highlight Ruby code in RDoc file?

Question

I am documenting a Ruby library I am writing. In my README.rdoc file, I am including an example of the usage with some demo Ruby code.

However, the resulting HTML documentation does not show the Ruby code with syntax highlighting, merely as a block of code.

When I look at the source of e.g. http://rdoc.rubyforge.org/README_rdoc.html, all I see is a piece of Ruby code, just like I included in my README.rdoc. Is there a special option to pass to the rdoc command?

Answer 1

You must use an RDoc template that includes syntax highlighting. There are many floating around the web.

(I agree with Phrogz, you should use YARD and also the Markdown syntax.)

Answer 2

RDoc, somewhat naively, uses the method below to determine if it can use the syntax highlighter.

   def parseable? text
     text =~ /\b(def|class|module|require) |=>|\{\s?\||do \|/ and
       text !~ /<%|%>/
   end

So your code will only be highlighted if it contains one of the following strings:

• def
• class
• module
• require
• =>
• { |
• do |