darkfish-rdoc 1.1.1

data/ChangeLog

@@ -0,0 +1,194 @@
+-- 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
+            LICENSE (new)
+            project.yml (new)
+            ChangeLog (new)
+            Rakefile.local (new)
+            lib/rdoc/generator/template/darkfish/js/darkfish.js (new) (and 1 other/s)
+   Changed: /trunk
+            lib/rdoc/generator/template/darkfish/classpage.rhtml
+            Rakefile
+            lib/darkfish-rdoc.rb
+   Deleted: lib/rdoc/generator/darkfish_generator.rb
+
+   Integrated new Rake build system.
+
+
+-- Tue, 29 Jul 2008 14:52:26 -0000 by deveiant (r17) -----
+   Changed: lib/darkfish-rdoc.rb
+
+   Fixed bug in darkfish-rdoc: 'generators' -> 'generator'
+
+
+-- Mon, 30 Jun 2008 19:06:36 -0000 by deveiant (r16) -----
+   Added:   lib/rdoc/generator
+            -> renamed from /trunk/lib/rdoc/generators@r14
+   Changed: Rakefile
+            lib/darkfish-rdoc.rb
+   Deleted: lib/rdoc/generators
+
+   Beginning conversion to Rdoc 2.0. Broken for now; see tags/RDOC_1 for a working
+   RDoc 1.x version.
+
+
+-- Wed, 21 May 2008 17:08:10 -0000 by deveiant (r14) -----
+   Added:   darkfish_preview.png (new)
+            lib/darkfish-rdoc.rb (new)
+   Changed: README
+            /trunk
+            Rakefile
+            lib/rdoc/generators/template/darkfish/js/jquery.js
+            lib/rdoc/generators/template/darkfish/classpage.rhtml
+            lib/rdoc/generators/darkfish_generator.rb (and 2 other/s)
+
+    * Added a `require`-able library that injects the generator into RDoc's known
+    generator hash.
+    * Modified method anchors to be the method name instead of a random number --
+    this will break URLs generated by RDoc, but I'd rather have sensible URLs.
+    * Added a javascript hook that highlights the current page target if there is one.
+    * Updated jQuery to 1.2.4
+
+
+-- Sat, 03 May 2008 02:56:54 -0000 by deveiant (r13) -----
+   Changed: lib/rdoc/generators/darkfish_generator.rb
+
+   Added some more output path debugging
+
+
+-- Tue, 18 Mar 2008 15:52:57 -0000 by deveiant (r12) -----
+   Added:   lib/rdoc/generators/template/darkfish/classpage.rhtml
+            -> renamed from /trunk/lib/rdoc/generators/template/classpage.rhtml@r10
+            lib/rdoc/generators/template/darkfish/index.rhtml
+            -> renamed from /trunk/lib/rdoc/generators/template/index.rhtml@r10
+            lib/rdoc/generators/template/darkfish (new)
+            lib/rdoc/generators/template/darkfish/filepage.rhtml
+            -> renamed from /trunk/lib/rdoc/generators/template/filepage.rhtml@r10
+            lib/rdoc/generators/template/darkfish/images
+            -> renamed from /trunk/lib/rdoc/generators/template/images@r10
+            lib/rdoc/generators/template/darkfish/js
+            -> renamed from /trunk/lib/rdoc/generators/template/js@r10 (and 2 other/s)
+   Changed: lib/rdoc/generators/darkfish_generator.rb
+            Rakefile
+            misc/rake/svn.rb
+   Deleted: lib/rdoc/generators/template/js
+            lib/rdoc/generators/template/rdoc.css
+            lib/rdoc/generators/template/classpage.rhtml
+            lib/rdoc/generators/template/index.rhtml
+            lib/rdoc/generators/template/filepage.rhtml
+            lib/rdoc/generators/template/images (and 1 other/s)
+
+    * Set up rdoc options to use itself for docs.
+    * Set up sensible package tasks
+    * Made the chatty output of the generator only show up if $DEBUG is turned on.
+    * Moved everything in the `template` directory into a `darkfish` subdirectory for interoperability
+    with other RDoc generators.
+
+
+-- Mon, 18 Feb 2008 14:33:06 -0000 by deveiant (r11) -----
+   Changed: README
+            lib/rdoc/generators/template/rdoc.css
+
+    * Updated README
+    * Fixed up CSS for the index page.
+
+
+-- Sat, 16 Feb 2008 08:11:47 -0000 by deveiant (r10) -----
+   Added:   README (new)
+            lib/rdoc (new)
+            lib/rdoc/generators/template
+            -> copied from /trunk/generators/template@r9
+            misc/prototype.html
+            -> renamed from /trunk/prototype.html@r8
+            lib (new)
+            lib/rdoc/generators
+            -> renamed from /trunk/generators@r8 (and 3 other/s)
+   Changed: /trunk
+            Rakefile
+            misc/rake/svn.rb
+   Deleted: index-prototype.html
+            misc/rake/verifytask.rb
+            prototype.html
+            generators
+
+    * Added README
+    * Rakefile
+    - Added an dog-food 'rdoc' task
+    - Fixed up the 'install' task
+    * Rearranged directories for easy building/installation.
+    * Put prototype HTML files into misc/
+
+
+-- Sat, 16 Feb 2008 06:19:51 -0000 by deveiant (r9) -----
+   Added:   misc/rake (new)
+            misc/rake/helpers.rb (new)
+            Rakefile (new)
+            misc/rake/svn.rb (new)
+            misc/rake/verifytask.rb (new)
+            misc (new) (and 1 other/s)
+   Changed: generators/template/rdoc.css
+            generators/template/classpage.rhtml
+            generators/darkfish_generator.rb
+
+   Reorganizing for release.
+
+
+-- Thu, 03 Jan 2008 19:40:24 -0000 by deveiant (r8) -----
+   Changed: generators/template/index.rhtml
+
+   Removed the description bit from the index page -- there's just no way to make it work gracefully.
+
+
+-- Fri, 19 Oct 2007 01:04:31 -0000 by deveiant (r7) -----
+   Changed: generators/template/rdoc.css
+            generators/template/classpage.rhtml
+
+   Fixes for C source documentation, a few CSS tweaks
+
+
+-- Thu, 18 Oct 2007 15:15:47 -0000 by deveiant (r6) -----
+   Added:   generators/template/images/macFFBgHack.png (new)
+   Changed: generators/template/rdoc.css
+
+   Fixed missing piece of ThickBox for FF on the Mac
+
+
+-- Fri, 12 Oct 2007 00:20:02 -0000 by deveiant (r5) -----
+   Changed: generators/darkfish_generator.rb
+
+   Add time constants for the time-detla calculations
+
+
+-- Thu, 11 Oct 2007 21:05:25 -0000 by deveiant (r4) -----
+   Changed: generators/template/rdoc.css
+            generators/darkfish_generator.rb
+
+    * Updated definition lists in the description to not look like ass.
+    * Documentation touchups.
+
+
+-- Wed, 10 Oct 2007 20:40:20 -0000 by deveiant (r3) -----
+   Changed: generators/darkfish_generator.rb
+
+   Added a Generators::DARKFISHGenerators alias to work around Rdoc's assumption that all formats are acronyms.
+
+
+-- Wed, 10 Oct 2007 19:33:33 -0000 by deveiant (r2) -----
+   Added:   generators/template/images/wrench_orange.png (new)
+            generators/template/images/zoom.png (new)
+            generators/template/js (new)
+            generators/template/images/wrench.png (new)
+            generators/template/rdoc.css (new)
+            generators/template/images/tag_green.png (new) (and 40 other/s)
+
+   Initial commit
+
+
+-- Wed, 10 Oct 2007 16:31:51 -0000 by deveiant (r1) -----
+   Added:   /trunk (new)
+            /branches (new)
+            /tags (new)
+
+   Setting up repository structure
+
+

data/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2008, Michael Granger
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+  * Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+  * Neither the name of the author/s, nor the names of the project's
+    contributors may be used to endorse or promote products derived from this
+    software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README

@@ -0,0 +1,100 @@
+= Darkfish Rdoc Generator
+
+This is a complete replacement for the default HTML generator for Rdoc. 
+
+I created it with a few goals in mind:
+
+* Replace the four-frame layout with three different indexes with a single-page, 
+  class/module-focused view.
+
+* I helped write what became the default look and feel for Rdoc, but it's 
+  starting to show its age. I wanted to update it with new CSS and Javascript 
+  for modern browsers.
+
+* Add some of the nifty searching and index-on-the-side stuff I liked from the
+  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.
+
+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
+tweak it to generate your own spiffy docs.
+
+It looks like this:
+
+http://deveiate.org/darkfish_preview.png
+
+== Getting Started
+
+If you haven't installed it yet, you can install it via RubyGems:
+
+ $ sudo gem install darkfish-rdoc
+
+Or download the source and do:
+	
+ $ sudo rake install
+
+== Usage
+
+To use it, just specify that you want 'darkfish' output instead of the default
+when you run Rdoc:
+
+ $ rdoc -w 4 -SHN -f darkfish -m README README lib
+
+Or from a Rakefile:
+
+  ### Task: rdoc
+  require 'rake/rdoctask'
+  gem 'darkfish-rdoc'
+
+  Rake::RDocTask.new do |rdoc|
+    rdoc.title    = "My Awesome SnoCone Library"
+  
+    rdoc.options += [
+        '-w', '4',
+        '-SHN',
+        '-f', 'darkfish', # This bit
+        '-m', 'README',
+      ]
+    
+    rdoc.rdoc_files.include 'README'
+    rdoc.rdoc_files.include 'lib/snocone.rb'
+  end
+  
+  
+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:
+
+  http://deveiate.org/projects/Darkfish-Rdoc/
+
+== License
+
+ Copyright (c) 2007, 2008, The FaerieMUD Consortium
+ All rights reserved.
+ 
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+ 
+ The above copyright notice and this permission notice shall be included in
+ all copies or substantial portions of the Software.
+ 
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ THE SOFTWARE.
+ 
+
+

data/Rakefile

@@ -0,0 +1,238 @@
+#!rake
+#
+# Darkfish-Rdoc rakefile
+#
+# Based on various other Rakefiles, especially one by Ben Bleything
+#
+# Copyright (c) 2008 The FaerieMUD Consortium
+#
+# Authors:
+#  * Michael Granger <ged@FaerieMUD.org>
+#
+
+BEGIN {
+	require 'pathname'
+	basedir = Pathname.new( __FILE__ ).dirname
+
+	libdir = basedir + "lib"
+	extdir = basedir + "ext"
+
+	$LOAD_PATH.unshift( libdir.to_s ) unless $LOAD_PATH.include?( libdir.to_s )
+	$LOAD_PATH.unshift( extdir.to_s ) unless $LOAD_PATH.include?( extdir.to_s )
+}
+
+
+require 'rbconfig'
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/clean'
+
+$dryrun = false
+
+### Config constants
+BASEDIR       = Pathname.new( __FILE__ ).dirname.relative_path_from( Pathname.getwd )
+LIBDIR        = BASEDIR + 'lib'
+EXTDIR        = BASEDIR + 'ext'
+DOCSDIR       = BASEDIR + 'docs'
+PKGDIR        = BASEDIR + 'pkg'
+
+PKG_NAME      = 'darkfish-rdoc'
+PKG_SUMMARY   = 'A pretty (different) Rdoc HTML generator'
+VERSION_FILE  = LIBDIR + 'darkfish-rdoc.rb'
+PKG_VERSION   = VERSION_FILE.read[ /VERSION = '(\d+\.\d+\.\d+)'/, 1 ]
+PKG_FILE_NAME = "#{PKG_NAME.downcase}-#{PKG_VERSION}"
+GEM_FILE_NAME = "#{PKG_FILE_NAME}.gem"
+
+ARTIFACTS_DIR = Pathname.new( ENV['CC_BUILD_ARTIFACTS'] || 'artifacts' )
+
+TEXT_FILES    = %w( Rakefile ChangeLog README LICENSE ).collect {|filename| BASEDIR + filename }
+LIB_FILES     = Pathname.glob( LIBDIR + '**/*.rb' ).delete_if {|item| item =~ /\.svn/ }
+EXT_FILES     = Pathname.glob( EXTDIR + '**/*.{c,h,rb}' ).delete_if {|item| item =~ /\.svn/ }
+
+SPECDIR       = BASEDIR + 'spec'
+SPEC_FILES    = Pathname.glob( SPECDIR + '**/*_spec.rb' ).delete_if {|item| item =~ /\.svn/ }
+
+TESTDIR       = BASEDIR + 'tests'
+TEST_FILES    = Pathname.glob( TESTDIR + '**/*.tests.rb' ).delete_if {|item| item =~ /\.svn/ }
+
+RAKE_TASKDIR  = BASEDIR + 'rake'
+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
+RELEASE_FILES << LOCAL_RAKEFILE if LOCAL_RAKEFILE.exist?
+
+COVERAGE_MINIMUM = ENV['COVERAGE_MINIMUM'] ? Float( ENV['COVERAGE_MINIMUM'] ) : 85.0
+RCOV_EXCLUDES = 'spec,tests,/Library/Ruby,/var/lib,/usr/local/lib'
+RCOV_OPTS = [
+	'--exclude', RCOV_EXCLUDES,
+	'--xrefs',
+	'--save',
+	'--callsites',
+	#'--aggregate', 'coverage.data' # <- doesn't work as of 0.8.1.2.0
+  ]
+
+
+# Subversion constants -- directory names for releases and tags
+SVN_TRUNK_DIR    = 'trunk'
+SVN_RELEASES_DIR = 'releases'
+SVN_BRANCHES_DIR = 'branches'
+SVN_TAGS_DIR     = 'tags'
+
+SVN_DOTDIR       = BASEDIR + '.svn'
+SVN_ENTRIES      = SVN_DOTDIR + 'entries'
+
+
+### Load some task libraries that need to be loaded early
+require RAKE_TASKDIR + 'helpers.rb'
+require RAKE_TASKDIR + 'svn.rb'
+require RAKE_TASKDIR + 'verifytask.rb'
+
+# Define some constants that depend on the 'svn' tasklib
+PKG_BUILD = get_svn_rev( BASEDIR ) || 0
+SNAPSHOT_PKG_NAME = "#{PKG_FILE_NAME}.#{PKG_BUILD}"
+SNAPSHOT_GEM_NAME = "#{SNAPSHOT_PKG_NAME}.gem"
+
+# Documentation constants
+RDOC_OPTIONS = [
+	'-w', '4',
+	'-SHN',
+	'-i', '.',
+	'-m', 'README',
+	'-W', 'http://deveiate.org/projects/Darkfish-Rdoc//browser/trunk/'
+  ]
+
+# Release constants
+SMTP_HOST = 'mail.faeriemud.org'
+SMTP_PORT = 465 # SMTP + SSL
+
+# Project constants
+PROJECT_HOST = 'deveiate.org'
+PROJECT_PUBDIR = "/usr/local/www/public/code"
+PROJECT_DOCDIR = "#{PROJECT_PUBDIR}/#{PKG_NAME}"
+PROJECT_SCPURL = "#{PROJECT_HOST}:#{PROJECT_DOCDIR}"
+
+# Rubyforge stuff
+RUBYFORGE_GROUP = 'deveiate'
+RUBYFORGE_PROJECT = 'darkfish-rdoc'
+
+# Gem dependencies: gemname => version
+DEPENDENCIES = {
+	'rdoc: >= 2.1.0' => '',
+}
+
+# Non-gem requirements: packagename => version
+REQUIREMENTS = {
+}
+
+# RubyGem specification
+GEMSPEC   = Gem::Specification.new do |gem|
+	gem.name              = PKG_NAME.downcase
+	gem.version           = PKG_VERSION
+
+	gem.summary           = PKG_SUMMARY
+	gem.description       = <<-EOD
+	A complete replacement for the default HTML generator for Rdoc, the
+	API documentation-extraction system for Ruby. 
+	EOD
+
+	gem.authors           = 'Michael Granger'
+	gem.email             = 'ged@FaerieMUD.org'
+	gem.homepage          = 'http://deveiate.org/projects/Darkfish-Rdoc/'
+	gem.rubyforge_project = RUBYFORGE_PROJECT
+
+	gem.has_rdoc          = true
+	gem.rdoc_options      = RDOC_OPTIONS
+
+	gem.files             = RELEASE_FILES.
+		collect {|f| f.relative_path_from(BASEDIR).to_s }
+	gem.test_files        = SPEC_FILES.
+		collect {|f| f.relative_path_from(BASEDIR).to_s }
+		
+	DEPENDENCIES.each do |name, version|
+		version = '>= 0' if version.length.zero?
+		gem.add_dependency( name, version )
+	end
+	
+	REQUIREMENTS.each do |name, version|
+		gem.requirements << [ name, version ].compact.join(' ')
+	end
+end
+
+$trace = Rake.application.options.trace ? true : false
+$dryrun = Rake.application.options.dryrun ? true : false
+
+
+# Load any remaining task libraries
+RAKE_TASKLIBS.each do |tasklib|
+	next if tasklib =~ %r{/(helpers|svn|verifytask)\.rb$}
+	begin
+		require tasklib
+	rescue ScriptError => err
+		fail "Task library '%s' failed to load: %s: %s" %
+			[ tasklib, err.class.name, err.message ]
+		trace "Backtrace: \n  " + err.backtrace.join( "\n  " )
+	rescue => err
+		log "Task library '%s' failed to load: %s: %s. Some tasks may not be available." %
+			[ tasklib, err.class.name, err.message ]
+		trace "Backtrace: \n  " + err.backtrace.join( "\n  " )
+	end
+end
+
+# Load any project-specific rules defined in 'Rakefile.local' if it exists
+import LOCAL_RAKEFILE if LOCAL_RAKEFILE.exist?
+
+
+#####################################################################
+###	T A S K S 	
+#####################################################################
+
+### Default task
+task :default  => [:clean, :spec, :rdoc, :package]
+
+
+### Task: clean
+CLEAN.include 'coverage'
+CLOBBER.include 'artifacts', 'coverage.info', PKGDIR
+
+# Target to hinge on ChangeLog updates
+file SVN_ENTRIES
+
+### Task: changelog
+file 'ChangeLog' => SVN_ENTRIES.to_s do |task|
+	log "Updating #{task.name}"
+
+	changelog = make_svn_changelog()
+	File.open( task.name, 'w' ) do |fh|
+		fh.print( changelog )
+	end
+end
+
+
+### Task: cruise (Cruisecontrol task)
+desc "Cruisecontrol build"
+task :cruise => [:clean, :spec, :package] do |task|
+	raise "Artifacts dir not set." if ARTIFACTS_DIR.to_s.empty?
+	artifact_dir = ARTIFACTS_DIR.cleanpath
+	artifact_dir.mkpath
+	
+	$stderr.puts "Copying coverage stats..."
+	FileUtils.cp_r( 'coverage', artifact_dir )
+	
+	$stderr.puts "Copying packages..."
+	FileUtils.cp_r( FileList['pkg/*'].to_a, artifact_dir )
+end
+
+
+desc "Update the build system to the latest version"
+task :update_build do
+	log "Updating the build system"
+	sh 'svn', 'up', RAKE_TASKDIR
+	log "Updating the Rakefile"
+	sh 'rake', '-f', RAKE_TASKDIR + 'Metarakefile'
+end
+