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
Jeff Rose <rosejn@gmail.com> [2005-04-26 17:18]:
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.
rdoc-include_dont_remove_comments.diff (720 Bytes)
···
--
Regards,
Tilman
Tilman Sauerbeck wrote:
Jeff Rose <rosejn@gmail.com> [2005-04-26 17:18]:
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.
------------------------------------------------------------------------
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
Hey, that patch of yours eats out all indentation. Here is the correct patch:
preprocess.rb.patch (452 Bytes)
···
On 04/26/2005 02:21 PM, Tilman Sauerbeck wrote:
Jeff Rose <rosejn@gmail.com> [2005-04-26 17:18]:
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.
------------------------------------------------------------------------
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}'"
''
--
Dr Balwinder Singh Dheeman Registered Linux User: #229709
CLLO (Chief Linux Learning Officer) Machines: #168573, 170593, 259192
Anu's Linux@HOME Distros: Ubuntu, Fedora, Knoppix
More: http://anu.homelinux.net/~bsd/ Visit: http://counter.li.org/