rogerdpack-hanna 0.1.7

data/Manifest

@@ -0,0 +1,22 @@
+bin/hanna
+hanna.gemspec
+lib/hanna/hanna.rb
+lib/hanna/rdoc_version.rb
+lib/hanna/rdoctask.rb
+lib/hanna/template_files/class_index.haml
+lib/hanna/template_files/file_index.haml
+lib/hanna/template_files/index.haml
+lib/hanna/template_files/layout.haml
+lib/hanna/template_files/method_index.haml
+lib/hanna/template_files/method_list.haml
+lib/hanna/template_files/method_search.js
+lib/hanna/template_files/page.haml
+lib/hanna/template_files/prototype-1.6.0.3.js
+lib/hanna/template_files/sections.haml
+lib/hanna/template_files/styles.sass
+lib/hanna/template_helpers.rb
+lib/hanna/template_page_patch.rb
+lib/hanna.rb
+Manifest
+Rakefile
+README.markdown

data/README.markdown

@@ -0,0 +1,102 @@
+# Hanna -- a better RDoc template
+
+Hanna is an RDoc template that scales. It's implemented in Haml, making the sources clean
+and readable. It's built with simplicity, beauty and ease of browsing in mind. (See more
+in [the wiki][wiki].)
+
+Hanna gem is available from [GitHub][]:
+
+    gem install mislav-hanna
+
+The template was created by [Mislav][] and since then has seen contributions from:
+
+1. [Tony Strauss](http://github.com/DesigningPatterns), who participated from the early
+   start and made tons of fixes and enhancements to the template;
+2. [Hongli Lai](http://blog.phusion.nl/) with the search filter for methods.
+
+
+## Usage
+
+There is a command-line tool installed with the Hanna gem:
+
+    hanna -h
+
+This is a wrapper over `rdoc` and it forwards all the parameters to it. Manual usage
+would require specifying Hanna as a template when invoking RDoc on the command-line:
+
+    rdoc -o doc --inline-source --format=html -T hanna lib/*.rb
+    
+Hanna requires the `--inline-source` (or `-S`) flag.
+
+An alternative is to set the `RDOCOPT` environment variable:
+
+    RDOCOPT="-S -f html -T hanna"
+
+This will make RDoc always use Hanna unless it is explicitly overridden.
+
+Another neat trick is to put the following line in your .gemrc:
+
+    rdoc: --inline-source --line-numbers --format=html --template=hanna
+
+This will make RubyGems use Hanna when generating documentation for installed gems.
+
+### Rake task
+
+For repeated generation of API docs, it's better to set up a Rake task. If you already
+have an `RDocTask` set up in your Rakefile, the only thing you need to change is this:
+
+    # replace this:
+    require 'rake/rdoctask'
+    # with this:
+    require 'hanna/rdoctask'
+
+Tip: you can do this in the Rakefile of your Rails project before running `rake doc:rails`.
+
+Here is an example of a task for the [will_paginate library][wp]:
+
+    # instead of 'rake/rdoctask':
+    require 'hanna/rdoctask'
+    
+    desc 'Generate RDoc documentation for the will_paginate plugin.'
+    Rake::RDocTask.new(:rdoc) do |rdoc|
+      rdoc.rdoc_files.include('README.rdoc', 'LICENSE', 'CHANGELOG').
+        include('lib/**/*.rb').
+        exclude('lib/will_paginate/named_scope*').
+        exclude('lib/will_paginate/array.rb').
+        exclude('lib/will_paginate/version.rb')
+      
+      rdoc.main = "README.rdoc" # page to start on
+      rdoc.title = "will_paginate documentation"
+      
+      rdoc.rdoc_dir = 'doc' # rdoc output folder
+      rdoc.options << '--webcvs=http://github.com/mislav/will_paginate/tree/master/'
+    end
+
+### Generating documentation for installed gems
+
+You can generate documentation for installed gems, which might be more convenient than the
+`gem rdoc` command with the +RDOCOPT+ environment variable set as described. For instance,
+to generate docs for "actionpack" and "activerecord" type:
+
+    [sudo] hanna --gems actionpack activerecord
+
+
+## You can help
+
+Don't like something? Think you can design better? (You probably can.)
+
+I think of Hanna as the first RDoc template that's actually _maintainable_. First thing I
+have done is converted the original HTML template to Haml and Sass, cleaning up and
+removing the (ridiculous amount of) duplication. Also, the template fragments are now in
+_separate files_.
+
+Ultimately, I'd like to lose the frameset. Currently that is far from possible because the
+whole RDoc HTML Generator is built for frames. Still, that is my goal.
+
+This is git. Fork it, hack away, tell me about it!
+
+
+[wiki]: http://github.com/mislav/hanna/wikis/home "Hanna wiki"
+[GitHub]: http://gems.github.com/ "GitHub gem server"
+[wp]: http://github.com/mislav/will_paginate/tree/master/Rakefile
+[Mislav]: http://mislav.caboo.se/ "Mislav Marohnić"

data/Rakefile

@@ -0,0 +1,21 @@
+# Encoding: utf-8
+require 'echoe'
+require 'lib/hanna/rdoc_version'
+
+Echoe.new('hanna') do |p|
+  p.version = '0.1.7'
+  
+  p.summary     = "An RDoc template that scales"
+  p.description = "Hanna is an RDoc implemented in Haml, making its source clean and maintainable. It's built with simplicity, beauty and ease of browsing in mind."
+  
+  p.author = 'Mislav Marohnić'
+  p.email  = 'mislav.marohnic@gmail.com'
+  p.url    = 'http://github.com/mislav/hanna'
+  
+  p.project = nil
+  p.has_rdoc = false
+  
+  p.runtime_dependencies << ['rdoc', Hanna::RDOC_VERSION_REQUIREMENT]
+  p.runtime_dependencies << ['haml', '~> 2.0.4']
+  p.runtime_dependencies << ['rake', '~> 0.8.2']
+end

data/bin/hanna

@@ -0,0 +1,81 @@
+#!/usr/bin/ruby
+if ARGV.size == 1 and (ARGV.first == '-h' || ARGV.first == '--help')
+  puts <<-HELP
+Hanna -- a better RDoc template
+Synopsis:
+  hanna [options]  [file names...]
+  [sudo] hanna --gems  [gem names...]
+  
+Example usage:
+
+  hanna lib/**/*.rb
+
+Hanna passes all arguments to RDoc. To find more about RDoc options, see
+"rdoc -h". Default options are:
+
+  -o doc --inline-source --charset=UTF-8
+
+The second form, with the "--gems" argument, serves the same purpose as
+the "gem rdoc" command: it generates documentation for installed gems.
+When no gem names are given, "hanna --gems" will install docs for EACH of
+the gems, which can, uh, take a little while.
+
+HELP
+  exit 0
+end
+
+unless RUBY_PLATFORM =~ /(:?mswin|mingw)/
+  require 'pathname'
+  hanna_dir = Pathname.new(__FILE__).realpath.dirname + '../lib'
+else
+  # windows
+  hanna_dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+end
+
+$:.unshift(hanna_dir) unless $:.include?(hanna_dir)
+
+require 'rubygems'
+require 'hanna/rdoc_version'
+Hanna::require_rdoc
+require 'rdoc/rdoc'
+
+options = []
+
+options << '-f' << 'html' << '-T' << 'hanna'
+options << '--inline-source' << '--charset=UTF-8'
+
+if ARGV.first == '--gems'
+  require 'rubygems/doc_manager'
+  Gem::DocManager.configured_args = options
+  
+  gem_names = ARGV.dup
+  gem_names.shift
+  
+  unless gem_names.empty?
+    specs = gem_names.inject([]) do |arr, name|
+      found = Gem::SourceIndex.from_installed_gems.find_name(name)
+      spec = found.sort_by {|s| s.version }.last
+      arr << spec if spec
+      arr
+    end
+  else
+    specs = Gem::SourceIndex.from_installed_gems.inject({}) do |all, pair|
+      full_name, spec = pair
+      if spec.has_rdoc? and (!all[spec.name] or spec.version > all[spec.name].version)
+        all[spec.name] = spec
+      end
+      all
+    end
+    specs = specs.values
+    puts "Hanna is installing documentation for #{specs.size} gem#{specs.size > 1 ? 's' : ''} ..."
+  end
+
+  specs.each do |spec|
+    Gem::DocManager.new(spec).generate_rdoc
+  end
+else
+  options << '-o' << 'doc' unless ARGV.include?('-o') or ARGV.include?('--op')
+  options.concat ARGV
+
+  RDoc::RDoc.new.document(options)
+end

data/hanna.gemspec

@@ -0,0 +1,40 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{hanna}
+  s.version = "0.1.7"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Mislav Marohni\304\207"]
+  s.date = %q{2009-02-17}
+  s.default_executable = %q{hanna}
+  s.description = %q{Hanna is an RDoc implemented in Haml, making its source clean and maintainable. It's built with simplicity, beauty and ease of browsing in mind.}
+  s.email = %q{mislav.marohnic@gmail.com}
+  s.executables = ["hanna"]
+  s.extra_rdoc_files = ["bin/hanna", "lib/hanna/hanna.rb", "lib/hanna/rdoc_version.rb", "lib/hanna/rdoctask.rb", "lib/hanna/template_files/class_index.haml", "lib/hanna/template_files/file_index.haml", "lib/hanna/template_files/index.haml", "lib/hanna/template_files/layout.haml", "lib/hanna/template_files/method_index.haml", "lib/hanna/template_files/method_list.haml", "lib/hanna/template_files/page.haml", "lib/hanna/template_files/sections.haml", "lib/hanna/template_files/styles.sass", "lib/hanna/template_files/prototype-1.6.0.3.js", "lib/hanna/template_files/method_search.js", "lib/hanna/template_helpers.rb", "lib/hanna/template_page_patch.rb", "lib/hanna.rb", "README.markdown"]
+  s.files = ["bin/hanna", "hanna.gemspec", "lib/hanna/hanna.rb", "lib/hanna/rdoc_version.rb", "lib/hanna/rdoctask.rb", "lib/hanna/template_files/class_index.haml", "lib/hanna/template_files/file_index.haml", "lib/hanna/template_files/index.haml", "lib/hanna/template_files/layout.haml", "lib/hanna/template_files/method_index.haml", "lib/hanna/template_files/method_list.haml", "lib/hanna/template_files/page.haml", "lib/hanna/template_files/sections.haml", "lib/hanna/template_files/styles.sass", "lib/hanna/template_files/prototype-1.6.0.3.js", "lib/hanna/template_files/method_search.js", "lib/hanna/template_helpers.rb", "lib/hanna/template_page_patch.rb", "lib/hanna.rb", "Manifest", "Rakefile", "README.markdown"]
+  s.homepage = %q{http://github.com/mislav/hanna}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Hanna", "--main", "README.markdown"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{An RDoc template that scales}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rdoc>, ["~> 2.3.0"])
+      s.add_runtime_dependency(%q<haml>, ["~> 2.0.4"])
+      s.add_runtime_dependency(%q<rake>, ["~> 0.8.2"])
+    else
+      s.add_dependency(%q<rdoc>, ["~> 2.3.0"])
+      s.add_dependency(%q<haml>, ["~> 2.0.4"])
+      s.add_dependency(%q<rake>, ["~> 0.8.2"])
+    end
+  else
+    s.add_dependency(%q<rdoc>, ["~> 2.3.0"])
+    s.add_dependency(%q<haml>, ["~> 2.0.4"])
+    s.add_dependency(%q<rake>, ["~> 0.8.2"])
+  end
+end

data/lib/hanna.rb

@@ -0,0 +1 @@
+require 'hanna/hanna'

data/lib/hanna/hanna.rb

@@ -0,0 +1,48 @@
+# = A better RDoc HTML template
+#
+# Authors: Mislav Marohnić <mislav.marohnic@gmail.com>
+#          Tony Strauss (http://github.com/DesigningPatterns)
+#          Michael Granger <ged@FaerieMUD.org>, who had maintained the original RDoc template
+
+require 'haml'
+require 'sass'
+require 'rdoc/generator/html'
+require 'hanna/template_page_patch'
+
+module RDoc::Generator::HTML::HANNA
+  class << self
+    def dir
+      @dir ||= File.join File.dirname(__FILE__), 'template_files'
+    end
+
+    def read(*names)
+      content = names.inject('') { |all, name| all << File.read(File.join(dir, name)) }
+      extension = names.first =~ /\.(\w+)$/ && $1
+
+      Hanna::TemplateHelpers.silence_warnings do
+        case extension
+        when 'sass'
+          Sass::Engine.new(content)
+        when 'haml'
+          Haml::Engine.new(content, :format => :html4, :filename => names.join(','))
+        else
+          content
+        end
+      end
+    end
+  end
+
+  STYLE = read('styles.sass')
+
+  CLASS_PAGE  = read('page.haml')
+  FILE_PAGE   = CLASS_PAGE
+  METHOD_LIST = read('method_list.haml', 'sections.haml')
+
+  FR_INDEX_BODY = BODY = read('layout.haml')
+
+  FILE_INDEX   = read('file_index.haml')
+  CLASS_INDEX  = read('class_index.haml')
+  METHOD_INDEX = read('method_index.haml')
+
+  INDEX = read('index.haml')
+end 

data/lib/hanna/rdoc_version.rb

@@ -0,0 +1,21 @@
+module Hanna
+  #
+  # The version of RDoc that Hanna should use.
+  #
+  RDOC_VERSION = '2.3.0'
+  RDOC_VERSION_REQUIREMENT = "~> #{RDOC_VERSION}"
+
+  #
+  # This method loads the correct version of RDoc.  If the correct
+  # version of RDoc is not present, this method will terminate the
+  # program with a helpful error message.
+  #
+  def self.require_rdoc
+    begin
+      gem 'rdoc', RDOC_VERSION_REQUIREMENT
+    rescue Gem::LoadError
+      $stderr.puts "Error: hanna requires the RDoc #{RDOC_VERSION} gem!"
+      exit 1
+    end 
+  end
+end

data/lib/hanna/rdoctask.rb

@@ -0,0 +1,42 @@
+require 'hanna/rdoc_version'
+require 'rake'
+require 'rake/rdoctask'
+
+Rake::RDocTask.class_eval do
+  # don't allow it
+  undef :external=, :template=
+  
+  # Create the tasks defined by this task lib.
+  def define
+    @template = 'hanna'
+    options << '--format=html'
+    
+    # inline source and UTF-8 are defaults:
+    options << '--inline-source' unless options.include? '--inline-source' or options.include? '-S'
+    options << '--charset=UTF-8' if options.grep(/^(--charset\b|-c\b)/).empty?
+    
+    desc "Build the HTML documentation"
+    task name
+    
+    desc "Force a rebuild of the RDOC files"
+    task paste("re", name) => [paste("clobber_", name), name]
+
+    desc "Remove rdoc products" 
+    task paste("clobber_", name) do
+      rm_r rdoc_dir rescue nil
+    end
+
+    task :clobber => [paste("clobber_", name)]
+      
+    directory @rdoc_dir
+    task name => [rdoc_target]
+    file rdoc_target => @rdoc_files + [Rake.application.rakefile] do
+      rm_r @rdoc_dir rescue nil
+      Hanna::require_rdoc
+      require 'rdoc/rdoc'
+      
+      RDoc::RDoc.new.document(option_list + @rdoc_files)
+    end
+    return self
+  end
+end

data/lib/hanna/template_files/class_index.haml

@@ -0,0 +1,3 @@
+%h1= values[:list_title]
+%ol#index-entries.classes
+  = render_class_tree make_class_tree(values[:entries])

data/lib/hanna/template_files/file_index.haml

@@ -0,0 +1,12 @@
+%h1= values[:list_title]
+- any_hidden = false
+
+%ol#index-entries{ :class => 'files' }
+  - for entry in values[:entries]
+    - hide = entry[:name] =~ /\.rb$/
+    - any_hidden = true if hide
+    %li{ :class => hide ? 'other' : nil }= link_to entry[:name], entry[:href]
+
+  - if any_hidden
+    %li
+      %a.show{ :href => '#', :onclick => 'this.parentNode.parentNode.className += " expanded"; this.parentNode.removeChild(this); return false' } show all

data/lib/hanna/template_files/index.haml

@@ -0,0 +1,11 @@
+!!! Frameset
+%html{ "xml:lang" => "en", :lang => "en", :xmlns => "http://www.w3.org/1999/xhtml" }
+  %head
+    %title= values[:title]
+    %meta{ :content => "text/html; charset=#{values[:charset]}", "http-equiv" => "Content-Type" }
+  %frameset{ :cols => "20%, *", :border => "1", :frameborder => "1", :bordercolor => "gray" }
+    %frameset{ :rows => "15%, 35%, 50%" }
+      %frame{ :name => "Files", :title => "Files", :src => "fr_file_index.html" }
+      %frame{ :name => "Classes", :src => "fr_class_index.html" }
+      %frame{ :name => "Methods", :src => "fr_method_index.html" }
+    %frame{ :name => "docwin", :src => values[:initial_page] }=""

data/lib/hanna/template_files/layout.haml

@@ -0,0 +1,34 @@
+!!! strict
+- index = values[:list_title]
+%html{ :lang => "en" }
+  %head
+    %title= values[:title]
+    %meta{ 'http-equiv' => "Content-Type", :content => "text/html; charset=#{values[:charset]}" }
+    %link{ :rel => "stylesheet", :href => values[:style_url], :type => "text/css", :media => "screen" }
+    - unless index
+      :javascript
+        function popupCode(url) {
+          window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
+        }
+
+        function toggleCode(id) {
+          var code = document.getElementById(id)
+
+          code.style.display = code.style.display != 'block' ? 'block' : 'none'
+          return true
+        }
+
+        // Make codeblocks hidden by default
+        document.writeln('<' + 'style type="text/css">.method .source pre { display: none }<\/style>')
+    - else
+      %base{ :target => 'docwin' }/
+        
+  %body{ :class => index ? 'list' : 'page' }
+    - if index
+      #index= yield
+    - else
+      #wrapper{ :class => values[:classmod] ? 'class' : 'file' }
+        = yield
+        #footer-push
+      #footer
+        = link_to '<strong>Hanna</strong> RDoc template', 'http://github.com/mislav/hanna/tree/master'