rdoc external include...

J

Jeff Rose

I'm working on a README file and I'm having trouble getting rdoc to do
what I want it to do. In a section with some short code examples I'd
like to include some ruby files from my examples directory rather than
putting the code into the file directly. So I can continue to edit and
run my sample code to make sure it always works, and I don't have to
edit two files every time I make a change.

Problem:
When I put this in the README file ":include:examples/sample.rb" it
does include the source, but it takes the # symbols off the comments in
the code, which makes it un-runnable if someone copy and pastes. (It
also looks lame...)

Anyone know how to have it include the source but either turn off rdoc
completely or treat it as regular stuff rather than cutting out #'s?

Thanks,
Jeff
 
T

Tilman Sauerbeck

--YZ5djTAD1cGYuMQK
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

Jeff Rose said:
Problem:
When I put this in the README file ":include:examples/sample.rb" it
does include the source, but it takes the # symbols off the comments in
the code, which makes it un-runnable if someone copy and pastes. (It
also looks lame...)

Anyone know how to have it include the source but either turn off rdoc
completely or treat it as regular stuff rather than cutting out #'s?

The attached patch should fix this, didn't try it though.

--
Regards,
Tilman

--YZ5djTAD1cGYuMQK
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="rdoc-include_dont_remove_comments.diff"

Only in ruby-1.8.2/lib/rdoc/markup/simple_markup: .preprocess.rb.swp
diff -aur ruby-1.8.2.orig/lib/rdoc/markup/simple_markup/preprocess.rb ruby-1.8.2/lib/rdoc/markup/simple_markup/preprocess.rb
--- ruby-1.8.2.orig/lib/rdoc/markup/simple_markup/preprocess.rb 2004-11-26 05:32:11.000000000 +0100
+++ ruby-1.8.2/lib/rdoc/markup/simple_markup/preprocess.rb 2005-04-26 10:49:09.000000000 +0200
@@ -43,7 +43,7 @@
def include_file(name, indent)
if (full_name = find_include_file(name))
content = File.open(full_name) {|f| f.read}
- res = content.gsub(/^#?/, indent)
+ res = content.gsub(/^\s*/, indent)
else
$stderr.puts "Couldn't find file to include: '#{name}'"
''

--YZ5djTAD1cGYuMQK--
 
J

Jeff Rose

Tilman said:
The attached patch should fix this, didn't try it though.



------------------------------------------------------------------------

Only in ruby-1.8.2/lib/rdoc/markup/simple_markup: .preprocess.rb.swp
diff -aur ruby-1.8.2.orig/lib/rdoc/markup/simple_markup/preprocess.rb ruby-1.8.2/lib/rdoc/markup/simple_markup/preprocess.rb
--- ruby-1.8.2.orig/lib/rdoc/markup/simple_markup/preprocess.rb 2004-11-26 05:32:11.000000000 +0100
+++ ruby-1.8.2/lib/rdoc/markup/simple_markup/preprocess.rb 2005-04-26 10:49:09.000000000 +0200
@@ -43,7 +43,7 @@
def include_file(name, indent)
if (full_name = find_include_file(name))
content = File.open(full_name) {|f| f.read}
- res = content.gsub(/^#?/, indent)
+ res = content.gsub(/^\s*/, indent)
else
$stderr.puts "Couldn't find file to include: '#{name}'"
''

This patch is a little better, but still not quite there. It includes
the file and leaves the comments, but it indents weird and strips out
all of the blank lines. I tried playing with the regexp to fix this,
but I don't know what rdoc is trying to do with indenation etc. so it
wasn't working out. What is this :include: directive supposed to be
used for? Is this an incorrect usage?

On a different note, I was wondering if people had advice on documenting
dynamic code. My classes have a large number of generated methods
(similar to attr_accessor) which I'd like to document. Actually, I'd
really like to generate the documentation or something so that it can be
done intelligently to support continued changes etc. Is this something
people do? Until this point I hadn't thought about the added complexity
of documenting dynamic code, but it almost seems like examples are the
only way to go...

Thanks,
Jeff Rose
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Similar Threads

[ANN] RDoc 3 6
Rdoc 1
rdoc and Rake::RDocTask with different outputs? 0
External JS file question 5
External CSS 4
[ANN] rdoc 3.3 Released 0
[ANN] RDoc 2.2.0 released 19
[ANN] rdoc 2.5 Released 7

Members online

No members online now.

Forum statistics

Threads
473,744
Messages
2,569,482
Members
44,901
Latest member
Noble71S45

Latest Threads

Top