darkfish-rdoc 1.1.1 → 1.1.2

data/ChangeLog

@@ -1,3 +1,55 @@
+-- Thu, 14 Aug 2008 00:59:07 -0000 by deveiant (r24) -----
+   Changed: /trunk
+            lib/rdoc/generator/darkfish.rb
+            Rakefile
+            lib/darkfish-rdoc.rb
+
+    * Updated build system
+
+
+-- Sat, 09 Aug 2008 01:14:22 -0000 by deveiant (r23) -----
+   Added:   spec/rdoc/generator (new)
+            spec/rdoc/generator/darkfish_spec.rb (new)
+            spec/rdoc (new)
+            spec (new)
+   Changed: project.yml
+            lib/rdoc/generator/template/darkfish/rdoc.css
+            lib/rdoc/generator/darkfish.rb
+            Rakefile
+            ChangeLog
+   Deleted: lib/rdoc/generator/template/darkfish/images/bullet_go.png
+            lib/rdoc/generator/template/darkfish/images/lightbulb.png
+            lib/rdoc/generator/template/darkfish/images/page_white_ruby.png
+            lib/rdoc/generator/template/darkfish/images/tag_blue.png
+            lib/rdoc/generator/template/darkfish/images/tag_blue_edit.png
+            lib/rdoc/generator/template/darkfish/images/bullet_toggle_plus.png (and 12 other/s)
+
+    * Updated build system.
+    * Fixed distributions, which didn't have the static files included with them.
+    * Removed a bunch of unused static files
+    * Fixed the path to the bg hack for Thickbox on Macs
+    * Added the beginnings of a test suite. Don't know yet how to test the generator in isolation.
+
+
+-- Fri, 08 Aug 2008 13:15:20 -0000 by deveiant (r22) -----
+   Changed: /trunk
+            Rakefile
+            project.yml
+   Deleted: misc/rake
+
+   Checkpoint commit
+
+
+-- Fri, 08 Aug 2008 02:47:22 -0000 by deveiant (r21) -----
+   Changed: README
+            lib/rdoc/generator/template/darkfish/classpage.rhtml
+            Rakefile
+            ChangeLog
+            lib/rdoc/generator/template/darkfish/js/darkfish.js
+
+   Checkpoint commit
+
+
 -- Thu, 07 Aug 2008 06:56:40 -0000 by deveiant (r18) -----
    Added:   lib/rdoc/generator/darkfish.rb
             -> renamed from /trunk/lib/rdoc/generator/darkfish_generator.rb@r16

data/README

@@ -15,8 +15,8 @@ I created it with a few goals in mind:
   modified Allison template (<URL:http://www.superalloy.nl/blog/?p=7>) Eloy 
   Duran came up with.
 
-* Implemented using ERB templates instead of Rdoc's constants-in-a-module style 
-  templating.
+* Implemented using separate ERB template files instead of Rdoc's 
+  constants-in-a-module style templating.
 
 I think I mostly succeeded, and it's nice enough that I wanted to use it for all
 my documentation, and I thought you might want to, too. Or at least be able to
@@ -38,16 +38,22 @@ Or download the source and do:
 
 == Usage
 
-To use it, just specify that you want 'darkfish' output instead of the default
-when you run Rdoc:
+Because of the way Rdoc and Rubygems work, there's currently no way to make the
+Darkfish generator available to Rdoc from the command line 'rdoc' tool if you 
+have it installed as a gem, but if you install it as a regular Ruby library 
+(via 'rake install'), you can do this:
 
  $ rdoc -w 4 -SHN -f darkfish -m README README lib
 
-Or from a Rakefile:
+I'm trying to figure out how to resolve this for the gem. Suggestions welcomed.
+
+You can, however, load the formatter as a gem from a Rakefile before you define 
+the RDocTask:
 
   ### Task: rdoc
   require 'rake/rdoctask'
-  gem 'darkfish-rdoc'
+  gem 'darkfish-rdoc' # Omit this if it's installed as a regular library
+  require 'darkfish-rdoc'
 
   Rake::RDocTask.new do |rdoc|
     rdoc.title    = "My Awesome SnoCone Library"
@@ -68,8 +74,8 @@ That's it.
 
 == Feedback
 
-I'd be happy to have feedback via email <URL: mailto:ged at FaerieMUD dot org> or a ticket on 
-the project's Trac:
+I'd be happy to have feedback via email <URL: mailto:ged at FaerieMUD dot org> 
+or a ticket on the project's Trac:
 
   http://deveiate.org/projects/Darkfish-Rdoc/
 

data/Rakefile

@@ -63,7 +63,17 @@ RAKE_TASKLIBS = Pathname.glob( RAKE_TASKDIR + '*.rb' )
 
 LOCAL_RAKEFILE = BASEDIR + 'Rakefile.local'
 
-RELEASE_FILES = TEXT_FILES + SPEC_FILES + TEST_FILES + LIB_FILES + EXT_FILES + RAKE_TASKLIBS
+EXTRA_PKGFILES = []
+EXTRA_PKGFILES.concat Pathname.glob( BASEDIR + 'lib/rdoc/generator/**/*.{css,rhtml,png,js}' ).delete_if {|item| item =~ /\.svn/ } 
+
+RELEASE_FILES = TEXT_FILES + 
+	SPEC_FILES + 
+	TEST_FILES + 
+	LIB_FILES + 
+	EXT_FILES + 
+	RAKE_TASKLIBS +
+	EXTRA_PKGFILES
+
 RELEASE_FILES << LOCAL_RAKEFILE if LOCAL_RAKEFILE.exist?
 
 COVERAGE_MINIMUM = ENV['COVERAGE_MINIMUM'] ? Float( ENV['COVERAGE_MINIMUM'] ) : 85.0
@@ -114,7 +124,8 @@ SMTP_PORT = 465 # SMTP + SSL
 PROJECT_HOST = 'deveiate.org'
 PROJECT_PUBDIR = "/usr/local/www/public/code"
 PROJECT_DOCDIR = "#{PROJECT_PUBDIR}/#{PKG_NAME}"
-PROJECT_SCPURL = "#{PROJECT_HOST}:#{PROJECT_DOCDIR}"
+PROJECT_SCPPUBURL = "#{PROJECT_HOST}:#{PROJECT_PUBDIR}"
+PROJECT_SCPDOCURL = "#{PROJECT_HOST}:#{PROJECT_DOCDIR}"
 
 # Rubyforge stuff
 RUBYFORGE_GROUP = 'deveiate'
@@ -122,7 +133,7 @@ RUBYFORGE_PROJECT = 'darkfish-rdoc'
 
 # Gem dependencies: gemname => version
 DEPENDENCIES = {
-	'rdoc: >= 2.1.0' => '',
+	'rdoc' => '>= 2.1.0',
 }
 
 # Non-gem requirements: packagename => version
@@ -192,7 +203,10 @@ import LOCAL_RAKEFILE if LOCAL_RAKEFILE.exist?
 #####################################################################
 
 ### Default task
-task :default  => [:clean, :spec, :rdoc, :package]
+task :default  => [:clean, :local, :spec, :rdoc, :package]
+
+### Task the local Rakefile can append to -- no-op by default
+task :local
 
 
 ### Task: clean

data/lib/darkfish-rdoc.rb

@@ -8,7 +8,7 @@ require 'pathname'
 require 'rdoc/rdoc' unless defined?( RDoc ) && defined?( RDoc::RDoc )
 
 ### Version for the Rakefile (update this in rdoc/generator/darkfish.rb too)
-# VERSION = '1.1.1'
+# VERSION = '1.1.2'
 
 begin
 	generator_dir = Pathname.new( __FILE__ ).dirname + 'rdoc/generator'

data/lib/rdoc/generator/darkfish.rb

@@ -1,7 +1,7 @@
 #!ruby
 #
 #  Darkfish RDoc HTML Generator
-#  $Id: darkfish.rb 18 2008-08-07 06:56:40Z deveiant $
+#  $Id: darkfish.rb 24 2008-08-14 00:59:07Z deveiant $
 #
 #  Author: Michael Granger <ged@FaerieMUD.org>
 #  
@@ -48,18 +48,22 @@ class RDoc::Generator::Darkfish < RDoc::Generator::XML
 	include ERB::Util
 
 	# Subversion rev
-	SVNRev = %$Rev: 18 $
+	SVNRev = %$Rev: 24 $
 	
 	# Subversion ID
-	SVNId = %$Id: darkfish.rb 18 2008-08-07 06:56:40Z deveiant $
+	SVNId = %$Id: darkfish.rb 24 2008-08-14 00:59:07Z deveiant $
 
 	# Path to this file's parent directory. Used to find templates and other
 	# resources.
 	GENERATOR_DIR = Pathname.new( __FILE__ ).expand_path.dirname
 
 	# Darkfish Version (update this in )
-	VERSION = '1.1.1'
-	
+	VERSION = '1.1.2'
+
+
+	#################################################################
+	###	C L A S S   M E T H O D S
+	#################################################################
 
 	### Standard generator factory method
 	def self::for( options )
@@ -67,6 +71,10 @@ class RDoc::Generator::Darkfish < RDoc::Generator::XML
 	end
 
 
+	#################################################################
+	###	I N S T A N C E   M E T H O D S
+	#################################################################
+
 	### Initialize a few instance variables before we start
 	def initialize( *args )
 		@template = nil
@@ -82,6 +90,14 @@ class RDoc::Generator::Darkfish < RDoc::Generator::XML
 	end
 	
 	
+	######
+	public
+	######
+
+	# The output directory
+	attr_reader :outputdir
+	
+	
 	### Output progress information if debugging is enabled
 	def debug_msg( *msg )
 		return unless $DEBUG
@@ -120,6 +136,7 @@ class RDoc::Generator::Darkfish < RDoc::Generator::XML
 
 	rescue StandardError => err
 		debug_msg "%s: %s\n  %s" % [ err.class.name, err.message, err.backtrace.join("\n  ") ]
+		raise
 	end
 
 
@@ -275,7 +292,7 @@ class RDoc::Generator::Darkfish < RDoc::Generator::XML
 	end
 
 
-	# %q$Id: darkfish.rb 18 2008-08-07 06:56:40Z deveiant $"
+	# %q$Id: darkfish.rb 24 2008-08-14 00:59:07Z deveiant $"
 	SVNID_PATTERN = /
 		\$Id:\s 
 			(\S+)\s					# filename

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

@@ -0,0 +1,276 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!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=utf-8" http-equiv="Content-Type" />
+
+	<title><%= classinfo['classmod'] %>: <%= classinfo['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>
+
+	<script type="text/javascript" charset="utf-8">
+		$(document).ready( function() {
+			hookSourceViews();
+			hookQuickSearch();
+			highlightLocationTarget();
+
+			$('ul.link-list a').bind( "click", highlightClickTarget );
+		});
+	</script>
+
+</head>
+<body class="<%= classinfo['classmod'].downcase %>">
+	
+	<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>
+					<% classinfo['infiles'].each do |file| %>
+						<li><a href="<%= rel_prefix %>/<%= file['full_path'] %>.html?TB_iframe=true&height=400&width=600"
+							class="thickbox" title="<%= file['full_path'] %>"><%= file['full_path'] %></a></li>
+					<% end %>
+					</ul>
+				</div>
+			</div>
+			
+			<% if !svninfo.empty? %>
+			<div id="file-svninfo-section" class="section">
+				<h3 class="section-header">Subversion Info</h3>
+				<div class="section-body">
+					<dl class="svninfo">
+						<dt>Rev</dt>
+						<dd><%= svninfo[:rev] %></dd>
+						
+						<dt>Last Checked In</dt>
+						<dd><%= svninfo[:commitdate].strftime('%Y-%m-%d %H:%M:%S') %> 
+							(<%= svninfo[:commitdelta] %> ago)</dd>
+						
+						<dt>Checked in by</dt>
+						<dd><%= svninfo[:committer] %></dd>
+					</dl>
+				</div>
+			</div>
+			<% end %>
+		</div>
+
+		<div id="class-metadata">
+
+			<!-- Parent Class -->
+			<% if classinfo['classmod'] == 'Class' %>
+			<div id="parent-class-section" class="section">
+				<h3 class="section-header">Parent</h3>
+				<% if classinfo['par_url'] %>
+				<p class="link"><a href="<%= classinfo['par_url'] %>"><%= classinfo['parent'] %></a></p>
+				<% else %>
+				<p class="link"><%= classinfo['parent'] %></p>
+				<% end %>
+			</div>
+			<% end %>
+
+			<!-- Namespace Contents -->
+			<% if classinfo['sections'].first.key?( 'classlist' ) %>
+			<div id="namespace-list-section" class="section">
+				<h3 class="section-header">Namespace</h3>
+				<ul class="link-list">
+					<% classinfo['sections'].first['classlist'].each do |desc| %>
+					<!-- Desc is: <%= desc.inspect %> -->
+					<li><%= desc.sub(/^(\w+)/, %Q{<span class="type">\\1</span>}) %></li>
+					<% end %>
+				</ul>
+			</div>
+			<% end %>
+
+			<!-- Method Quickref -->
+			<% if classinfo.key?( 'methods' ) %>
+			<div id="method-list-section" class="section">
+				<h3 class="section-header">Methods</h3>
+				<ul class="link-list">
+					<% classinfo['methods'].each do |meth| %>
+					<li><a href="#<%= meth['name'] %>"><%= meth['name']
+					 	%></a></li>
+					<% end %>
+				</ul>
+			</div>
+			<% end %>
+
+			<!-- Included Modules -->
+			<% if classinfo['includes'] %>
+			<div id="includes-section" class="section">
+				<h3 class="section-header">Included Modules</h3>
+				<ul class="link-list">
+				<% classinfo['includes'].each do |inc| %>
+				<% if inc['aref'].nil? %>
+					<li><span class="include"><%= inc['name'] %></span></li>
+				<% else %>
+					<li><a class="include" href="<%= inc['aref'] %>"><%= inc['name'] %></a></li>
+				<% end %>
+				<% end %>
+				</ul>
+			</div>
+			<% end %>
+		</div>
+	
+		<div id="project-metadata">
+			<div id="classindex-section" class="section project-section">
+				<h3 class="section-header">Class Index</h3>
+				<ul class="link-list">
+				<% modsort.each do |cname| %>
+				<% cinfo = classes[cname] %>
+					<li><a href="<%= rel_prefix %>/<%= cinfo[:outfile] %>"><%= cname %></a></li>
+				<% end %>
+				</ul>
+				<div id="no-class-search-results" style="display: none;">No matching classes.</div>
+				
+				<form action="#" method="get" accept-charset="utf-8">
+				<fieldset>
+					<legend>Quicksearch</legend>
+					<input type="text" name="quicksearch" value="" 
+						class="quicksearch-field" />
+				</fieldset>
+				</form>
+			</div>
+		</div>
+	</div>
+
+	<div id="documentation">
+		<% if classinfo['classmod'] == 'Class' %>
+		<h1 class="class"><%= classinfo['full_name'] %></h1>
+		<% else %>
+		<h1 class="module"><%= classinfo['full_name'] %></h1>
+		<% end %>
+
+		<div id="description">
+			<%= classinfo['description'] %>
+		</div>
+
+
+		<!-- Constants -->
+		<% if classinfo['sections'].first['constants'] %>
+		<div id="constants-list" class="section">
+			<h3 class="section-header">Constants</h3>
+			<dl>
+			<% classinfo['sections'].first['constants'].each do |const| %>
+				<dt><a name="<%= const['name'] %>"><%= const['name'] %></a></dt>
+				<% if const['desc'] %>
+				<dd class="description"><%= const['desc'].strip %></dd>
+				<% else %>
+				<dd class="description missing-docs">(Not documented)</dd>
+				<% end %>
+			<% end %>
+			</dl>
+		</div>
+		<% end %>
+
+		<!-- Attributes -->
+		<% if classinfo['sections'].first['attributes'] %>
+		<div id="attribute-method-details" class="method-section section">
+			<h3 class="section-header">Attributes</h3>
+
+			<% classinfo['sections'].first['attributes'].each do |attrib| %>
+			<div id="<%= attrib['name'].downcase.gsub(/[^a-z]+/, '-') %>-attribute-method" class="method-detail">
+				<a name="<%= attrib['name'] %>"></a>
+				<% if attrib['rw'] =~ /w/i %>
+				<a name="<%= 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['a_desc'] && !attrib['a_desc'].empty? %>
+				<%= attrib['a_desc'].strip %>
+				<% else %>
+				<p class="missing-docs">(Not documented)</p>
+				<% end %>
+				</div>
+			</div>
+			<% end %>
+		</div>
+		<% end %>
+
+		<!-- Methods -->
+		<% if classinfo['sections'].first['method_list'] %>
+		<% classinfo['sections'].first['method_list'].each do |methodlist| %>
+		<div id="<%= methodlist['type'].downcase %>-<%= methodlist['category'].downcase %>-method-details" class="method-section section">
+			<h3 class="section-header"><%= methodlist['type'] %> <%= methodlist['category'] %> Methods</h3>
+
+			<% methodlist['methods'].each do |methodinfo| %>
+			<% if methodinfo['m_desc'] =~ /Alias for/ %>
+			<div id="<%= methodinfo['name'].gsub( /[^a-z]+/, '-' ) %>-method" class="method-detail method-alias">
+			<% else %>
+			<div id="<%= methodinfo['name'].gsub( /[^a-z]+/, '-' ) %>-method" class="method-detail">
+			<% end %>
+				<a name="<%= methodinfo['name'] %>"></a>
+
+				<div class="method-heading">
+					<span class="method-name"><%= methodinfo['name'] %></span><span 
+						class="method-args"><%= methodinfo['params'] %></span>
+					<span class="method-click-advice">click to toggle source</span>
+				</div>
+
+				<div class="method-description">
+					<% if methodinfo['m_desc'] %>
+	          		<p><%= methodinfo['m_desc'].strip %></p>
+					<% else %>
+	          		<p class="missing-docs">(Not documented)</p>
+					<% end %>
+					
+					<% if methodinfo['sourcecode'] %>
+	          		<div class="method-source-code" 
+						id="<%= methodinfo['name'].gsub( /[^a-z]+/, '-' ) %>-source">
+<pre>
+<%= methodinfo['sourcecode'] %>
+</pre>
+	          		</div>
+					<% end %>
+				</div>
+
+				<% if methodinfo['aka'] %>
+				<div class="aliases">
+					Also aliased as: <%= methodinfo['aka'].collect do |aliasinfo|
+						%{<a href="#{aliasinfo['aref']}">#{aliasinfo['name']}</a>}
+					end.join(", ") %>
+				</div>
+				<% end %>
+			</div>
+			<% end %>
+		</div>
+		<% end %>
+		<% end %>
+
+	  </div>
+	</div>
+
+
+	<div id="rdoc-debugging-section-dump">
+	<% classinfo['sections'].first.keys.each do |section| %>
+		<div class="section">
+		<h2 class="section-header"><%= section %></h2>
+	
+		<pre><%= h classinfo['sections'].first[section].to_yaml %></pre>
+		</div>
+	<% 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></small>.</p>
+	</div>
+
+</body>
+</html>
+