Re: Rdoc with hyperlinks

On Jul 18, 2006, at 8:05, [email protected] wrote:

Ken B. wrote:
In general, you should not rely on knowledge of the source code to
understand how a library works, because the library writer reserves
the right to change the behavior of things that are not specified in
the documentation.

Ken - I certainly agree in theory. However, in practice, that is often
the only way to understand most Ruby libs.

No kidding.

OK, I gritted my teeth and ignored you the first time I saw your
request, but this time I couldn’t let it go. Took almost five hours to
solve. Sigh.

There’s a very good reason you couldn’t figure out how to do it by
looking at the RDoc source. The necessary path simply isn’t available;
by the time RDoc is generating output, it no longer knows where the
original source code file was.

Make the following changes to files in …/lib/rdoc

code_objects.rb:
Insert at line 467
     attr_accessor :source_path
Insert at line 483
     @source_path              = File.join(Dir.getwd,file_name)

This will modify class TopLevel so it looks like this:

class TopLevel < Context
attr_accessor :file_stat
attr_accessor :file_relative_name
attr_accessor :file_absolute_name
attr_accessor :source_path
attr_accessor :diagram

 @@all_classes = {}
 @@all_modules = {}

 def TopLevel::reset
   @@all_classes = {}
   @@all_modules = {}
 end

 def initialize(file_name)
   super()
   @name = "TopLevel"
   @file_relative_name = file_name
   @file_absolute_name = file_name
   @source_path        = File.join(Dir.getwd,file_name)
   @file_stat          = File.stat(file_name)
   @diagram            = nil
 end

Make the following changes to generators/html_generator.rb
Insert at line 877
@values[“source_path”] = CGI.escapeHTML(@context.source_path)
Change line 1031 from
‘charset’ => @options.charset
to
‘charset’ => @options.charset,
‘source_path’=> @context.parent.toplevel.source_path,
‘source_file’=> @context.parent.toplevel.file_relative_name

The first addition makes the “%source_path%” variable available for
most of the templates by changing HtmlFile::file_attribute_values to
look like

   @values["short_name"]   = CGI.escapeHTML(short_name)
   @values["full_path"]    = CGI.escapeHTML(full_path)
   @values["source_path"]  = CGI.escapeHTML(@context.source_path)
   @values["dtm_modified"] = @context.file_stat.mtime.to_s

The second makes the new source_path available for the pop-up source
code windows, by modifying HtmlMethod::create_source_code_file to look
like this:

def create_source_code_file(code_body)
   meth_path = @html_class.path.sub(/\.html$/, '.src')
   File.makedirs(meth_path)
   file_path = File.join(meth_path, @seq) + ".html"

   template = TemplatePage.new(RDoc::Page::SRC_PAGE)
   File.open(file_path, "w") do |f|
     values = {
       'title'     => CGI.escapeHTML(index_name),
       'code'      => code_body,
       'style_url' => style_url(file_path, @options.css),
       'charset'   => @options.charset,
       'source_path'=> @context.parent.toplevel.source_path,
       'source_file'=> @context.parent.toplevel.file_relative_name
     }
     template.write_html_on(f, values)
   end
   HTMLGenerator.gen_url(path, file_path)
 end

Finally, you need to edit whatever HTML template you’re using. If
you’re using the default HTML template
(generators/templates/html/html.rb) you might want to find the
FILE_PAGE and change

      <td>%full_path%

to

%full_path% [Source]

Another possible place to add a link is inside the pop-up source code
pages. Find SRC_PAGE, and change

%code%


to

Open %source_file%

%code%


or something along those lines.

Dave H. wrote:

OK, I gritted my teeth and ignored you the first time I saw your
request, but this time I couldn’t let it go. Took almost five hours to
solve. Sigh.

Thanks, greatly appreciated!

There’s a very good reason you couldn’t figure out how to do it by
looking at the RDoc source. The necessary path simply isn’t available;
by the time RDoc is generating output, it no longer knows where the
original source code file was.

Dave - I’m a little confused here. RDoc templates always have a link
to the files where the class comes from. However, the “file” pages
have no source code - only any file level RDoc, if there is any. But
RDoc must have the path to those files.

How would you modify RDoc to, instead of just including file level Rdoc
on file pages, include the full, formatted, source of the file (just
like it does for methods)?

On Jul 18, 2006, at 5:19 PM, Dave H. wrote:

Make the following changes to files in …/lib/rdoc

Can you turn this into a patch?


Eric H. - [email protected] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com

On Jul 20, 2006, at 5:47 PM, Dave H. wrote:

Slightly longer answer: “Um, I dunno. What kind of a patch, to be
applied with what tool? I’ve never made a patch. Is it hard?”

One way:

diff -u your_version_with_changes.rb original_version.rb > your.patch

If you changed more than one file I would suggest

diff -u your_version_of_whole_src_tree_directory
original_version_of_source_tree_directory > your.patch

the people who ask for patches will know how to use the patch tool to
apply it.

On Jul 20, 2006, at 10:43, Eric H. wrote:

On Jul 18, 2006, at 5:19 PM, Dave H. wrote:

Make the following changes to files in …/lib/rdoc

Can you turn this into a patch?

Short answer: “no”.

Slightly longer answer: “Um, I dunno. What kind of a patch, to be
applied with what tool? I’ve never made a patch. Is it hard?”

On Jul 20, 2006, at 10:53 PM, Logan C. wrote:

Can you turn this into a patch?

diff -u your_version_with_changes.rb original_version.rb > your.patch

If you changed more than one file I would suggest

diff -u your_version_of_whole_src_tree_directory
original_version_of_source_tree_directory > your.patch

the people who ask for patches will know how to use the patch tool
to apply it.

Ack!!! I lied. I always mix that up.

its diff -u original your_version

Sorry :(.

On 7/20/06, Logan C. [email protected] wrote:

One way:

Ack!!! I lied. I always mix that up.

its diff -u original your_version

Sorry :(.

If making a patch between two directory trees, you’ll also need the -r
option:

diff -ur foo_original foo_modified > foo_mychanges.patch

—John

I think we should have options for linking to the actual file (in the
original source), a rdoc highlighted html copy, or both.

On Jul 20, 2006, at 7:53 PM, Logan C. wrote:

applied with what tool? I’ve never made a patch. Is it hard?"
the people who ask for patches will know how to use the patch tool
to apply it.

The easiest way is to check out ruby from CVS:

http://www.ruby-lang.org/en/20020106.html

Make your changes, test them, then run cvs diff -u and send the
output to me.


Eric H. - [email protected] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com

This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.

| Privacy Policy | Terms of Service | Remote Ruby Jobs