# Including source in RDoc

**URL:** <https://www.ruby-forum.com/t/including-source-in-rdoc/81686>\
**Category:** Ruby\
**Created:** [January 11, 2007, 9:41am UTC](https://www.ruby-forum.com/t/including-source-in-rdoc/81686 "2007-01-11T09:41:01Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![oscar-alexander](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/o/e36b37/32.png) [@oscar-alexander](https://www.ruby-forum.com/u/oscar-alexander)\
**Post date:** [January 11, 2007, 9:41am UTC](https://www.ruby-forum.com/t/including-source-in-rdoc/81686/1 "2007-01-11T09:41:01Z")

</div>

Hi,

There was a Ruby Q. 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"?\> foo.rb Thu Jan 11 17:27:34 +0900 2007 

```
 <description>

```

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
```

```
 </description>
 <contents>
  </contents>

```

 Files: 1 Classes: 0 Modules: 0 Methods: 0 Elapsed: 0.214s

Alex G.

Bioinformatics Center  
Kyoto University

---

<div class="post-metadata">

**Author:** ![oscar-alexander](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/o/e36b37/32.png) [@oscar-alexander](https://www.ruby-forum.com/u/oscar-alexander)\
**Post date:** [January 11, 2007, 11:05am UTC](https://www.ruby-forum.com/t/including-source-in-rdoc/81686/2 "2007-01-11T11:05:14Z")

</div>

Alle 09:39, giovedì 11 gennaio 2007, Alex G. ha scritto:

> options seem to be:  
> though. My questions is: ‘Is there a better way?’.
> 
> # Foo.new.bar
> \<?xml version="1.0" encoding="utf-8"?\>
> 
> RDoc documentation Here is the Foo class. It doesn‘t do much.
> 
> Bioinformatics Center Kyoto University

In my opinion, there’s also a third option: instead of postprocessing  
the  
script when it’s run, preprocess the file when you generate the  
documentation. Instead of generating the doc directly using rdoc, use a  
script which turns the parts you want included into comments. This is a  
simple attempt at doing it:  
[file generate\_rdoc.rb]

require ‘tempfile’  
require ‘rdoc/rdoc’

def format\_sources lines  
to\_format=false  
begin\_regexp=/^#BEGIN\_RDOC\_SOURCE$/  
end\_regexp=/^#END\_RDOC\_SOURCE$/  
formatted=lines.map do |l|  
if to\_format and !l.match end\_regexp then “##{l}”  
elsif to\_format and l.match end\_regexp  
to\_format=false  
nil  
elsif l.match begin\_regexp  
to\_format=true  
nil  
else l  
end  
end  
formatted.compact  
end

if $0== **FILE**  
lines=File.readlines(‘demo.rb’)  
Tempfile.open(‘demo’) do |f|  
f.write format\_sources(lines).join("#\n")  
f.flush  
RDoc::RDoc.new.document([f.path])  
end  
end

This script takes the demo.rb file, creates a temp file where the text  
included between #BEGIN\_RDOC\_SOURCE and #END\_RDOC\_SOURCE commnents is  
commented, then runs rdoc on it. For instance, the demo.rb file could  
look  
like this

[file demo.rb]

# A class whose source you don’t want to appear in the doc

class A  
…  
end

#A class whose source you want in the doc  
#BEGIN\_RDOC\_SOURCE  
class B  
…  
end  
#END\_RDOC\_SOURCE

The temp file will be:

[temp file]

# A class whose source you don’t want to appear in the doc

class A  
…  
end

#A class whose source you want in the doc  
#class B  
#…  
#end

If you want something more complex, you of course need a more advanced  
script,  
but, in my opinion, this is the best way to go, expecially taking into  
account the fact that, being demo files, your users may want to look  
into  
them to understand how to use the library, and they may be confused to  
find  
the body of the script commented out.

I hope this helps

Stefano

---

<div class="post-metadata">

**Author:** ![oscar-alexander](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/o/e36b37/32.png) [@oscar-alexander](https://www.ruby-forum.com/u/oscar-alexander)\
**Post date:** [January 19, 2007, 4:29pm UTC](https://www.ruby-forum.com/t/including-source-in-rdoc/81686/3 "2007-01-19T16:29:42Z")

</div>

On Thu, 2007-01-11 at 19:04 +0900, Stefano C. wrote:

> In my opinion, there’s also a third option: instead of postprocessing the  
> script when it’s run, preprocess the file when you generate the  
> documentation. Instead of generating the doc directly using rdoc, use a  
> script which turns the parts you want included into comments. This is a  
> simple attempt at doing it:

I suppose another (though not immediate) option would be to make a  
request to modify RDoc to accomplish this, or do it yourself and submit  
a patch.

I don’t know much about the RDoc layout, but I would think that a change  
so that you had a series of start/stop tags that don’t interfere with  
code, but allow for documentation processing:

def func1  
…  
end

# START DOC PROCESSING

def func 2  
…  
end

# END DOC PROCESSING

should allow for the code to remain unchanged, and a properly modified  
RDoc could still process this into documentation.

Matt