rdoc_chm 2.3.0 → 2.4.0

data/History.txt

@@ -1,3 +1,27 @@
+=== 2.4.0 / 2009-08-10
+
+* Two major enhancementsd
+  * RDoc 2.4.x compatibility
+    - Converted to RHTML templates
+    - --opname option was removed form RDoc. RDoc_chm now uses --op for naming the CHM file
+  * Improved table of contents and index.
+    - TOC is now split into classes/modules and files
+    - index now lists methods followed by their class, i.e. 'to_s (Symbol)'
+
+* Multiple minor enhancements:
+  * fixed issue when klass.superclass is nil 
+  * moved file metadata into documentation div for single column layout 
+  * moved class metadata into documentation div for single column layout 
+  * removed method list from index page.  takes a long time to load on ruby-core and stdlib.   
+    (plus the data is given in the CHM TOC and index).
+  * added classindex and fileindex pages
+  * Readme fixes 
+  * udpated TOC from "Classes" to "Classes/Modules" 
+  * TOC uses method.pretty_name instead of method.name 
+  * added hidden img tags to index.rhtml so the html help compiler will find image files
+  * fixes to chm project and contents files
+  * Readme corrections
+
 === 2.3.0 / 2008-12-29
 
 * 1 major enhancement

data/Manifest.txt

@@ -1,7 +1,41 @@
-History.txt
-Manifest.txt
-README.txt
-Rakefile
-lib/rdoc/discover.rb
-lib/rdoc/generator/chm.rb
-lib/rdoc/generator/chm/chm.rb
+History.txt
+Manifest.txt
+README.rdoc
+Rakefile
+lib/rdoc/discover.rb
+lib/rdoc/generator/chm.rb
+lib/rdoc/generator/template/chm/.document
+lib/rdoc/generator/template/chm/chm_index.rhtml
+lib/rdoc/generator/template/chm/classindex.rhtml
+lib/rdoc/generator/template/chm/classpage.rhtml
+lib/rdoc/generator/template/chm/contents.rhtml
+lib/rdoc/generator/template/chm/fileindex.rhtml
+lib/rdoc/generator/template/chm/filepage.rhtml
+lib/rdoc/generator/template/chm/hpp_file.rhtml
+lib/rdoc/generator/template/chm/images/brick.png
+lib/rdoc/generator/template/chm/images/brick_link.png
+lib/rdoc/generator/template/chm/images/bug.png
+lib/rdoc/generator/template/chm/images/bullet_black.png
+lib/rdoc/generator/template/chm/images/bullet_toggle_minus.png
+lib/rdoc/generator/template/chm/images/bullet_toggle_plus.png
+lib/rdoc/generator/template/chm/images/date.png
+lib/rdoc/generator/template/chm/images/find.png
+lib/rdoc/generator/template/chm/images/loadingAnimation.gif
+lib/rdoc/generator/template/chm/images/macFFBgHack.png
+lib/rdoc/generator/template/chm/images/package.png
+lib/rdoc/generator/template/chm/images/page_green.png
+lib/rdoc/generator/template/chm/images/page_white_text.png
+lib/rdoc/generator/template/chm/images/page_white_width.png
+lib/rdoc/generator/template/chm/images/plugin.png
+lib/rdoc/generator/template/chm/images/ruby.png
+lib/rdoc/generator/template/chm/images/tag_green.png
+lib/rdoc/generator/template/chm/images/wrench.png
+lib/rdoc/generator/template/chm/images/wrench_orange.png
+lib/rdoc/generator/template/chm/images/zoom.png
+lib/rdoc/generator/template/chm/index.rhtml
+lib/rdoc/generator/template/chm/js/darkfish.js
+lib/rdoc/generator/template/chm/js/jquery.js
+lib/rdoc/generator/template/chm/js/quicksearch.js
+lib/rdoc/generator/template/chm/js/thickbox-compressed.js
+lib/rdoc/generator/template/chm/rdoc.css
+

data/README.rdoc

@@ -0,0 +1,40 @@
+= \RDoc_CHM
+
+* {RDoc_CHM Project Page}[http://github.com/vertiginous/rdoc_chm]
+* {RDoc_CHM Bug Tracker}[http://github.com/vertiginous/rdoc_chm/issues]
+
+== DESCRIPTION:
+
+A Microsoft Compiled HTML Help generator for {RDoc}[http://rdoc.rubyforge.org/].
+
+== FEATURES/PROBLEMS:
+
+
+== SYNOPSIS:
+
+  gem 'rdoc'
+  require 'rdoc/rdoc'
+  
+  RDoc::RDoc.new.document "-f chm", # ... see RDoc
+
+Or at the command line:
+
+  rdoc --fmt chm
+
+== REQUIREMENTS:
+
+* A Windows OS
+* RDoc 2.4
+* Requires installation of Microsoft's HTML Help Workshop 
+    You can download a copy for free from:
+      http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
+== INSTALL:
+
+* gem install rdoc_chm
+
+== LICENSE:
+
+RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers.  It is
+free software, and may be redistributed under the terms specified in the
+README file of the Ruby distribution.
+

data/Rakefile

@@ -1,22 +1,43 @@
-# -*- ruby -*-
-
-require 'rubygems'
-require 'hoe'
-
-$:.unshift 'lib'
-require 'rdoc/rdoc'
-require 'rdoc/generator/chm'
-
-Hoe.new 'rdoc_chm', RDoc::Generator::CHM::VERSION do |p|
-  p.rubyforge_name = 'rdoc'
-
-  p.developer 'Eric Hodel', 'drbrain@segment7.net'
-  p.developer 'Dave Thomas', ''
-  p.developer 'Tony Strauss', 'tony.strauss@designingpatterns.com'
-
-  p.extra_deps << ['rdoc', '~> 2.3']
-  p.extra_dev_deps << ['minitest', '~> 1.3']
-  p.spec_extras['required_rubygems_version'] = '>= 1.3'
-end
-
-# vim: syntax=Ruby
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+
+$:.unshift 'lib'
+
+require 'rdoc/generator/chm'
+
+Hoe.plugin :git
+
+Hoe.spec 'rdoc_chm' do |rdoc_chm|
+  rdoc_chm.rubyforge_name = 'rdoc'
+
+  rdoc_chm.developer 'Gordon Thiesfeld', 'gthiesfeld@gmail.com'
+  rdoc_chm.developer 'Eric Hodel', 'drbrain@segment7.net'
+  rdoc_chm.developer 'Dave Thomas', ''
+  rdoc_chm.developer 'Tony Strauss', 'tony.strauss@designingpatterns.com'
+
+  rdoc_chm.readme_file = 'README.rdoc'
+
+  rdoc_chm.extra_deps << ['rdoc', '>= 2.4']
+
+  rdoc_chm.testlib = :minitest
+
+  rdoc_chm.extra_dev_deps << ['minitest', '~> 1.3']
+  rdoc_chm.spec_extras['required_rubygems_version'] = '>= 1.3'
+  rdoc_chm.spec_extras['homepage'] = 'http://rdoc.rubyforge.org/rdoc_chm'
+end
+
+desc "Build chm files"
+task :chm => :clean do
+  sh %q{ rdoc --fmt chm --op rdoc_chm --title="rdoc_chm 2.4.0" --main=README.rdoc . }
+end
+
+task :clobber_chm do
+  rm_rf "rdoc_chm"
+end
+
+desc "rebuild chm files"
+task :rechm => [:clobber_chm, :chm] 
+
+# vim: syntax=Ruby

data/lib/rdoc/generator/chm.rb

@@ -1,24 +1,29 @@
-gem 'rdoc', '~> 2.3'
-require 'rdoc/generator/html'
+gem 'rdoc', '>= 2.4'
+require 'rdoc/generator/darkfish'
 
-class RDoc::Generator::CHM < RDoc::Generator::HTML
+class RDoc::AnyMethod
+  
+  ##
+  # Full method name for the CHM's index.
+  # in the format:  
+  #      method (Class)
 
-  VERSION = '2.3.0'
+  def chm_index_name  
+    "#{name} (#{@parent.full_name})"
+  end
 
-  RDoc::RDoc.add_generator self
+end
 
-  HHC_PATH = "c:/Program Files/HTML Help Workshop/hhc.exe"
+class RDoc::Generator::CHM < RDoc::Generator::Darkfish
 
-  ##
-  # Standard generator factory
+  VERSION = '2.4.0'
 
-  def self.for(options)
-    new(options)
-  end
+  RDoc::RDoc.add_generator( self )
+
+  HHC_PATH = "c:/Program Files/HTML Help Workshop/hhc.exe"
 
-  def initialize(*args)
+  def initialize(options)
     super
-    @op_name = @options.op_name || "rdoc"
     check_for_html_help_workshop
   end
 
@@ -37,80 +42,81 @@ class RDoc::Generator::CHM < RDoc::Generator::HTML
   ##
   # Generate the html as normal, then wrap it in a help project
 
-  def generate(info)
+  def generate( top_levels )
     super
-    @project_name = @op_name + ".hhp"
-    create_help_project
+    @project_name = "#{@outputdir.basename}.hhp"
+    generate_help_project
   end
 
   ##
   # The project contains the project file, a table of contents and an index
 
-  def create_help_project
-    create_project_file
-    create_contents_and_index
+  def generate_help_project
+    debug_msg "Generating the help project files"
+    generate_file_index
+    generate_class_index
+    generate_project_file
+    generate_contents
+    generate_chm_index
     compile_project
   end
 
+  def generate_file_index
+    templatefile = @template_dir + 'fileindex.rhtml'
+
+    outfile = @outputdir + "fileindex.html"
+    debug_msg "  rendering #{outfile}"
+    self.render_template( templatefile, binding(), outfile )
+  end
+
+  def generate_class_index
+    templatefile = @template_dir + 'classindex.rhtml'
+
+    outfile = @outputdir + "classindex.html"
+    debug_msg "  rendering #{outfile}"
+    self.render_template( templatefile, binding(), outfile )
+  end
+
   ##
   # The project file links together all the various
   # files that go to make up the help.
+  def generate_project_file
+    templatefile = @template_dir + 'hpp_file.rhtml'
+
+    @values = { :title => @options.title, :opname => @outputdir.basename }
+    
+    static_files = ['index.html', 'classindex.html', 'fileindex.html']
+    @values[:html_files] = static_files + (@files+@classes).map{|f| f.path }
+    
+    outfile = @outputdir + @project_name
+    debug_msg "  rendering #{outfile}"
+    self.render_template( templatefile, binding(), outfile )
+  end
 
-  def create_project_file
-    template = RDoc::TemplatePage.new @template::HPP_FILE
-    values = { "title" => @options.title, "opname" => @op_name }
-    files = []
-    @files.each do |f|
-      files << { "html_file_name" => f.path }
-    end
-
-    values['all_html_files'] = files
+  ##
+  # generate the CHM contents (contents.hhc)
+  def generate_contents
+    templatefile = @template_dir + 'contents.rhtml'
 
-    File.open(@project_name, "w") do |f|
-      template.write_html_on(f, values)
-    end
+    outfile = @outputdir + "contents.hhc"
+    debug_msg "  rendering #{outfile}"
+    self.render_template( templatefile, binding(), outfile )
   end
 
   ##
-  # The contents is a list of all files and modules.
-  # For each we include  as sub-entries the list
-  # of methods they contain. As we build the contents
-  # we also build an index file
-
-  def create_contents_and_index
-    contents = []
-    index    = []
-
-    (@files+@classes).sort.each do |entry|
-      content_entry = { "c_name" => entry.name, "ref" => entry.path }
-      index << { "name" => entry.name, "aref" => entry.path }
-
-      internals = []
-
-      methods = entry.build_method_summary_list(entry.path)
-
-      content_entry["methods"] = methods unless methods.empty?
-      contents << content_entry
-      index.concat methods
-    end
-
-    values = { "contents" => contents }
-    template = RDoc::TemplatePage.new @template::CONTENTS
-    File.open("contents.hhc", "w") do |f|
-      template.write_html_on(f, values)
-    end
-
-    values = { "index" => index }
-    template = RDoc::TemplatePage.new @template::CHM_INDEX
-    File.open("index.hhk", "w") do |f|
-      template.write_html_on(f, values)
-    end
+  # generate the CHM index (index.hhk)
+  def generate_chm_index
+    templatefile = @template_dir + 'chm_index.rhtml'
+    
+    outfile = @outputdir + "index.hhk"
+    debug_msg "  rendering #{outfile}"
+    self.render_template( templatefile, binding(), outfile )
   end
 
   ##
   # Invoke the windows help compiler to compiler the project
-
   def compile_project
+    debug_msg "  compiling #{@project_name}"
     system(HHC_PATH, @project_name)
   end
 

data/lib/rdoc/generator/template/chm/chm_index.rhtml

@@ -0,0 +1,27 @@
+!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<HTML>
+<HEAD>
+<meta name="GENERATOR" content="Microsoft&reg; HTML Help Workshop 4.1">
+<!-- Sitemap 1.0 -->
+</HEAD><BODY>
+<OBJECT type="text/site properties">
+	<param name="Foreground" value="0x80">
+	<param name="Window Styles" value="0x800025">
+	<param name="ImageType" value="Folder">
+</OBJECT>
+<UL>
+<% (@files+@classes).sort.each do |index| %>
+	<LI> <OBJECT type="text/sitemap">
+		<param name="Name" value="<%= index.full_name %>">
+		<param name="Local" value="<%= index.path %>">
+		</OBJECT>
+
+<% index.method_list.sort.each do |method|  %>
+	<LI> <OBJECT type="text/sitemap">
+		<param name="Name" value="<%= method.chm_index_name %>">
+		<param name="Local" value="<%= method.path %>">
+		</OBJECT>
+<% end # index.method_list.sort %>
+<% end # (@files+@classes).sort %>
+</UL>
+</BODY></HTML>

data/lib/rdoc/generator/template/chm/classindex.rhtml

@@ -0,0 +1,28 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+	<meta content="text/html; charset=<%= @options.charset %>" http-equiv="Content-Type" />
+
+	<title>Classes/Modules</title>
+
+	<link type="text/css" media="screen" href="rdoc.css" rel="stylesheet" />
+
+</head>
+<body class="indexpage">	
+
+	<% $stderr.sync = true %>
+	<h1><%= h @options.title %></h1>
+
+  <p>This is the API documentation for '<%= @options.title %>'.</p>
+  
+  <h2>Classes/Modules</h2>
+	<ul>
+		<% @modsort.each do |klass| %>
+		<li class="<%= klass.type %>"><a href="<%= klass.path %>"><%= klass.full_name %></a></li>
+		<% end %>
+	</ul>
+
+</body>
+</html>

data/lib/rdoc/generator/template/chm/classpage.rhtml

@@ -0,0 +1,204 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+	<meta content="text/html; charset=<%= @options.charset %>" http-equiv="Content-Type" />
+
+	<title><%= klass.type.capitalize %>: <%= klass.full_name %></title>
+
+	<link rel="stylesheet" href="<%= rel_prefix %>/rdoc.css" type="text/css" media="screen" />
+
+	<script src="<%= rel_prefix %>/js/jquery.js" type="text/javascript"
+		charset="utf-8"></script>
+	<script src="<%= rel_prefix %>/js/thickbox-compressed.js" type="text/javascript"
+		charset="utf-8"></script>
+	<script src="<%= rel_prefix %>/js/quicksearch.js" type="text/javascript"
+		charset="utf-8"></script>
+	<script src="<%= rel_prefix %>/js/darkfish.js" type="text/javascript"
+		charset="utf-8"></script>
+
+</head>
+<body class="<%= klass.type %>">
+
+	<div id="documentation">
+
+		<h1 class="<%= klass.type %>"><%= klass.full_name %></h1>
+
+
+	<!--<div id="metadata"> -->
+		<div id="file-metadata">
+			<div id="file-list-section" class="section">
+				<h3 class="section-header">In Files</h3>
+				<div class="section-body">
+					<ul>
+					<% klass.in_files.each do |tl| %>
+						<li><a href="<%= rel_prefix %>/<%= h tl.path %>"
+							title="<%= h tl.absolute_name %>"><%= h tl.absolute_name %></a></li>
+					<% end %>
+					</ul>
+				</div>
+			</div>
+
+		<div id="class-metadata">
+
+			<!-- Parent Class -->
+			<% if klass.type == 'class' %>
+			<div id="parent-class-section" class="section">
+				<h3 class="section-header">Parent</h3>
+				<% unless String === klass.superclass or klass.superclass.nil? %>
+				<p class="link"><a href="<%= klass.aref_to klass.superclass.path %>"><%= klass.superclass.full_name %></a></p>
+				<% else %>
+				<p class="link"><%= klass.superclass %></p>
+				<% end %>
+			</div>
+			<% end %>
+
+			<!-- Included Modules -->
+			<% unless klass.includes.empty? %>
+			<div id="includes-section" class="section">
+				<h3 class="section-header">Included Modules</h3>
+				<ul class="link-list">
+				<% klass.each_include do |inc| %>
+				<% unless String === inc.module %>
+					<li><a class="include" href="<%= klass.aref_to inc.module.path %>"><%= inc.module.full_name %></a></li>
+				<% else %>
+					<li><span class="include"><%= inc.name %></span></li>
+				<% end %>
+				<% end %>
+				</ul>
+			</div>
+			<% end %>
+		</div>
+
+			<% if $DEBUG_RDOC %>
+			<div id="debugging-toggle"><img src="<%= rel_prefix %>/images/bug.png"
+				alt="toggle debugging" height="16" width="16" /></div>
+			<% end %>
+		</div>
+	<!-- </div> -->
+
+		<div id="description">
+			<%= klass.description %>
+		</div>
+
+		<!-- Constants -->
+		<% unless klass.constants.empty? %>
+		<div id="constants-list" class="section">
+			<h3 class="section-header">Constants</h3>
+			<dl>
+			<% klass.each_constant do |const| %>
+				<dt><a name="<%= const.name %>"><%= const.name %></a></dt>
+				<% if const.comment %>
+				<dd class="description"><%= const.description.strip %></dd>
+				<% else %>
+				<dd class="description missing-docs">(Not documented)</dd>
+				<% end %>
+			<% end %>
+			</dl>
+		</div>
+		<% end %>
+
+		<!-- Attributes -->
+		<% unless klass.attributes.empty? %>
+		<div id="attribute-method-details" class="method-section section">
+			<h3 class="section-header">Attributes</h3>
+
+			<% klass.each_attribute do |attrib| %>
+			<div id="<%= attrib.html_name %>-attribute-method" class="method-detail">
+				<a name="<%= h attrib.name %>"></a>
+				<% if attrib.rw =~ /w/i %>
+				<a name="<%= h attrib.name %>="></a>
+				<% end %>
+				<div class="method-heading attribute-method-heading">
+					<span class="method-name"><%= h attrib.name %></span><span
+						class="attribute-access-type">[<%= attrib.rw %>]</span>
+				</div>
+
+				<div class="method-description">
+				<% if attrib.comment %>
+				<%= attrib.description.strip %>
+				<% else %>
+				<p class="missing-docs">(Not documented)</p>
+				<% end %>
+				</div>
+			</div>
+			<% end %>
+		</div>
+		<% end %>
+
+		<!-- Methods -->
+		<% klass.methods_by_type.each do |type, visibilities|
+			 next if visibilities.empty?
+			 visibilities.each do |visibility, methods|
+				 next if methods.empty? %>
+		<div id="<%= visibility %>-<%= type %>-method-details" class="method-section section">
+			<h3 class="section-header"><%= visibility.to_s.capitalize %> <%= type.capitalize %> Methods</h3>
+
+		<% methods.each do |method| %>
+			<div id="<%= method.html_name %>-method" class="method-detail <%= method.is_alias_for ? "method-alias" : '' %>">
+				<a name="<%= h method.aref %>"></a>
+
+				<div class="method-heading">
+				<% if method.call_seq %>
+					<span class="method-callseq"><%= method.call_seq.strip.gsub(/->/, '&rarr;').gsub( /^\w.*?\./m, '') %></span>
+					<span class="method-click-advice">click to toggle source</span>
+				<% else %>
+					<span class="method-name"><%= h method.name %></span><span
+						class="method-args"><%= method.params %></span>
+					<span class="method-click-advice">click to toggle source</span>
+				<% end %>
+				</div>
+
+				<div class="method-description">
+					<% if method.comment %>
+					<%= method.description.strip %>
+					<% else %>
+					<p class="missing-docs">(Not documented)</p>
+					<% end %>
+
+					<% if method.token_stream %>
+					<div class="method-source-code"
+						id="<%= method.html_name %>-source">
+<pre>
+<%= method.markup_code %>
+</pre>
+					</div>
+					<% end %>
+				</div>
+
+				<% unless method.aliases.empty? %>
+				<div class="aliases">
+					Also aliased as: <%= method.aliases.map do |aka|
+						%{<a href="#{ klass.aref_to aka.path}">#{h aka.name}</a>}
+					end.join(", ") %>
+				</div>
+				<% end %>
+			</div>
+
+		<% end %>
+		</div>
+	<% end
+		 end %>
+
+	</div>
+
+
+	<div id="rdoc-debugging-section-dump" class="debugging-section">
+	<% if $DEBUG_RDOC
+			 require 'pp' %>
+<pre><%= h PP.pp(klass, _erbout) %></pre>
+		</div>
+	<% else %>
+		<p>Disabled; run with --debug to generate this.</p>
+	<% end %>
+	</div>
+
+	<div id="validator-badges">
+		<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+		<p><small>Generated with the <a href="http://deveiate.org/projects/Darkfish-Rdoc/">Darkfish
+			Rdoc Generator</a> <%= RDoc::Generator::Darkfish::VERSION %></small>.</p>
+	</div>
+
+</body>
+</html>
+