From: Alex Gutteridge <alexg@...>
Date: 2007-01-11T17:39:55+09:00
Subject: Including source in RDoc

Hi,

There was a Ruby Quiz on literate programming a little while back,  
but I couldn't quite find an answer to my problem there, so I'm  
coming to the group.

I'm writing some small example scripts to demo my library, and I'd  
like a way of including the source of these scripts in the  
documentation generated by RDoc. Trouble is, I can't see anyway of  
telling RDoc to include the source in the generated HTML, so my  
options seem to be:

1. Include a copy of the source in the comments of the same file  
(simple, but seems a bit un-DRY-ish)
2. Comment the code (so RDoc sees it) and then post-process the file  
when the script is run.

I've implemented the second option as shown in the foo.rb file below.  
When run directly, it evals anything indented by two or more spaces  
as Ruby code. Other comments are left alone. When RDoc sees it it  
treats the code as pre-formatted text. It all feels a bit hacky  
though. My questions is: 'Is there a better way?'.

[alexg@powerbook]/Users/alexg/Desktop(21): cat foo.rb
#RDoc documentation
#Here is the Foo class. It doesn't do much.
#  class Foo
#    def bar
#      puts 'bar'
#    end
#  end
#All you can do is call bar on it as shown:
#  Foo.new.bar

if __FILE__ == $0
   eval(IO.read($0).gsub(/^\#\s\s/,''))
end
[alexg@powerbook]/Users/alexg/Desktop(22): ruby foo.rb
bar
[alexg@powerbook]/Users/alexg/Desktop(23): rdoc -f xml foo.rb

                              foo.rb:
Generating XML...
<?xml version="1.0" encoding="utf-8"?>
<rdoc>
<file-list>
   <file name="foo.rb" id="foo.rb">
     <file-info>
       <path>foo.rb</path>
       <dtm-modified>Thu Jan 11 17:27:34 +0900 2007</dtm-modified>
     </file-info>

     <description>
<p>
RDoc documentation Here is the Foo class. It doesn&#8216;t do much.
</p>
<pre>
   class Foo
     def bar
       puts 'bar'
     end
   end
</pre>
<p>
All you can do is call bar on it as shown:
</p>
<pre>
   Foo.new.bar
</pre>

     </description>
     <contents>
      </contents>

   </file>
</file-list>
<class-module-list>
</class-module-list>
</rdoc>
Files:   1
Classes: 0
Modules: 0
Methods: 0
Elapsed: 0.214s

Alex Gutteridge

Bioinformatics Center
Kyoto University