mislav-hanna 0.1.1 → 0.1.2

data/README.markdown

@@ -2,18 +2,31 @@
 
 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.
+browsing in mind. (See more in [the wiki][wiki].)
 
-Hanna is available from [GitHub][]:
+Hanna was made by [Mislav][] and is available from [GitHub][]:
 
     gem install mislav-hanna
 
-After that you have two options. You can use the command-line tool:
+
+## Usage
+
+After installing, you have three options. You can use the command-line tool:
 
     hanna -h
 
-For repeated generation of API docs, it's better to set up a Rake task. Here is
-an example for [will_paginate][]:
+For repeated generation of API docs, it's better to set up a Rake task. If you
+already have an `RDocTask` set up, 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'
@@ -35,7 +48,10 @@ an example for [will_paginate][]:
     
 Either way, it's the same as using RDoc.
 
-Hanna was crafted by [Mislav][].
+The last thing you can do with Hanna is generate documentation for installed
+gems. This is a replacement for the "gem rdoc" command.
+
+    [sudo] hanna --gems haml will_paginate
 
 ## A work in progress
 
@@ -59,7 +75,8 @@ Don't like something? Think you can design better? (You probably can.)
 This is git. I welcome all submissions towards my goal.
 
 
+[wiki]: http://github.com/mislav/hanna/wikis/home "Hanna wiki"
 [GitHub]: http://gems.github.com/ "GitHub gem source"
-[will_paginate]: http://github.com/mislav/will_paginate
+[wp]: http://github.com/mislav/will_paginate
 [Mislav]: http://mislav.caboo.se/ "Mislav Marohnić"
 [Allison]: http://blog.evanweaver.com/files/doc/fauna/allison/ "A modern, pretty RDoc template"

data/bin/hanna

@@ -2,15 +2,24 @@
 if ARGV.size == 1 and ARGV.first == '-h'
   puts <<-HELP
 Hanna -- a better RDoc template
-Sample usage:
+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:
+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
@@ -33,9 +42,40 @@ require 'hanna/rdoc_patch'
 options = []
 
 options << '-T' << 'hanna/hanna.rb'
-options << '-o' << 'doc' unless ARGV.include?('-o') or ARGV.include?('--op')
 options << '--inline-source' << '--charset=UTF-8'
 
-options.concat ARGV
+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.search(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)
+  RDoc::RDoc.new.document(options)
+end

data/lib/hanna/hanna.rb

@@ -1,16 +1,15 @@
+# = 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'
 
-# = A better RDoc HTML template
-#
-# Many different kinds of awesome.
-#
-# Author: Mislav Marohnić <mislav.marohnic@gmail.com>
-# Based on the work of Michael Granger <ged@FaerieMUD.org>
-
-module RDoc::Generator::HTML::Hanna
+module RDoc::Generator::HTML::HANNA
   class << self
     def dir
       @dir ||= File.join File.dirname(__FILE__), 'template_files'

data/lib/hanna/rdoctask.rb

@@ -10,8 +10,9 @@ Rake::RDocTask.class_eval do
     unless @template and @template != 'html'
       @template = File.dirname(__FILE__) + '/hanna'
     end
+    # 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$|-c\b)/).empty?
+    options << '--charset=UTF-8' if options.grep(/^(--charset\b|-c\b)/).empty?
     
     desc "Build the HTML documentation"
     task name
@@ -32,9 +33,9 @@ Rake::RDocTask.class_eval do
       rm_r @rdoc_dir rescue nil
       
       begin
-        gem 'rdoc', '~> 2.0.0'
+        gem 'rdoc', '~> 2.1.0'
       rescue Gem::LoadError
-        $stderr.puts "Couldn't load RDoc 2.0 gem"
+        $stderr.puts "Couldn't load RDoc 2.1 gem"
       end
       require 'rdoc/rdoc'
       require 'hanna/rdoc_patch'

data/lib/hanna/template_files/file_index.haml

@@ -1,4 +1,13 @@
 %h1= values["list_title"]
-%ol#index-entries{ :class => values["list_title"].downcase }
+- type = values["list_title"].downcase
+- any_hidden = false
+
+%ol#index-entries{ :class => type }
   - for entry in values["entries"]
-    %li= link_to entry['name'], entry['href']
+    - hide = type == 'files' && 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

@@ -3,7 +3,7 @@
   %head
     %title= values["title"]
     %meta{ :content => "text/html; charset=#{values['charset']}", "http-equiv" => "Content-Type" }
-  %frameset{ :cols => "20%, *", :frameborder => 'no' }
+  %frameset{ :cols => "20%, *" }
     %frameset{ :rows => "15%, 35%, 50%" }
       %frame{ :name => "Files", :title => "Files", :src => "fr_file_index.html" }
       %frame{ :name => "Classes", :src => "fr_class_index.html" }

data/lib/hanna/template_files/page.haml

@@ -20,11 +20,14 @@
         == (#{link_to 'view online', values["cvsurl"]})
   - else
     %ol.paths
-      - for file in values["infiles"]
-        %li
+      - values["infiles"].each_with_index do |file, index|
+        %li{ :class => index > 0 ? 'other' : nil }
           = link_to file["full_path"], file["full_path_url"]
           - if file["cvsurl"]
             == (#{link_to 'view online', file["cvsurl"]})
+      - if values["infiles"].size > 1
+        %li
+          %a.show{ :href => '#', :onclick => 'this.parentNode.parentNode.className += " expanded"; this.parentNode.removeChild(this); return false' } show all
           
   - if values["parent"] then
     .parent
@@ -39,8 +42,9 @@
 #content
   - if values["diagram"]
     #diagram= values["diagram"]
-    
-  - if values["description"]
-    #description~ values["description"]
-    
-  = yield
+
+  #text
+    - if values["description"]
+      #description~ values["description"]
+
+    = yield

data/lib/hanna/template_files/sections.haml

@@ -4,17 +4,17 @@
       %h2= link_to section["sectitle"], section["secsequence"]
       - if section["seccomment"]
         .section-comment= section["seccomment"]
-    - if values["classlist"]
+    - if section["classlist"]
       #class-list
         %h3 Classes and Modules
-        = values["classlist"]
+        = section["classlist"]
         
-    - if values["constants"]
+    - if section["constants"]
       #constants-list
         %h3.section-bar Constants
         .name-list
           %table{ :summary => "Constants" }
-            - for const in values["constants"]
+            - for const in section["constants"]
               %tr.top-aligned-row.context-row
                 %td.context-item-name
                   = const["name"]
@@ -22,48 +22,48 @@
                   \=
                 %td.context-item-value
                   = const["value"]
-                - if values["desc"] then
+                - if const["desc"] then
                   %td{ :width => "3em" }
                      
                   %td.context-item-desc
                     = const["desc"]
                     
-    - if values["aliases"]
+    - if section["aliases"]
       #aliases-list
         %h3.section-bar External Aliases
         .name-list
           %table{ :summary => "aliases" }
-            - for alia in values["aliases"]
+            - for alia in section["aliases"]
               %tr.top-aligned-row.context-row
                 %td.context-item-name
-                  = values["old_name"]
+                  = alia["old_name"]
                 %td
                   \->
                 %td.context-item-value
-                  = values["new_name"]
-              - if values["desc"] then
+                  = alia["new_name"]
+              - if alia["desc"] then
                 %tr.top-aligned-row.context-row
                   %td
                      
                   %td.context-item-desc{ :colspan => "2" }
-                    = values["desc"]
+                    = alia["desc"]
                     
-    - if values["attributes"]
+    - if section["attributes"]
       #attribute-list
         %h3.section-bar Attributes
         .name-list
           %table
-            - for attr in values["attributes"]
+            - for attr in section["attributes"]
               %tr.top-aligned-row.context-row
                 %td.context-item-name
-                  = values["name"]
-                - if values["rw"] then
+                  = attr["name"]
+                - if attr["rw"] then
                   %td.context-item-value
-                    = "[#{values['rw']}]"
+                    = "[#{attr['rw']}]"
                 - else
                   %td.context-item-value  
                 %td.context-item-desc
-                  = values["a_desc"]
+                  = attr["a_desc"]
     
     - if section["method_list"]
       #methods

data/lib/hanna/template_files/styles.sass

@@ -1,9 +1,12 @@
-!title_font = Times, "Times New Roman", Georgia, serif
-!code_font  = Inconsolata, Monaco, "DejaVu Sans", Courier, "Courier New", monospace
+!title_font = Georgia, serif
+!code_font_family = Monaco, "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Courier New", monospace
+!code_font_size   = 14px
+!code_font = !code_font_size !code_font_family
 
 !light_link = #369
 !link = !light_link - 40
 !light_text = #666
+!dark_blue_text = #0E3062
 
 html, body
   :height 100%
@@ -19,11 +22,9 @@ body
   :height auto !important
   :height 100%
   :margin 0 auto -43px
-  :border-left 1px solid gray
 #footer-push
   :height 43px
 div.header, #footer
-  :font-size 80%
   :background #eee
 #footer
   :border-top 1px solid silver
@@ -32,6 +33,7 @@ div.header, #footer
   :line-height 30px
   :text-align center
   :font-variant small-caps
+  :font-size 95%
 
 // self-clearing
 .clearing
@@ -61,7 +63,7 @@ a
     :color = !light_link
     &:hover
       :color #eee
-  h1, h2, h3
+  h1, h2, h3, h4, h5, h6
     a
       :color = !link
 
@@ -71,7 +73,12 @@ ol
   :list-style none
   li
     :margin-left 0
-    white-space: nowrap
+    :white-space nowrap
+    &.other
+      :display none
+ol.expanded li.other
+  :display list-item
+      
 table
   :margin-bottom 1em
   :font-size 1em
@@ -86,6 +93,17 @@ table
   tr
     :border-bottom 1px solid silver
 
+#index, div.header
+  a.show
+    :text-decoration underline
+    :font-style italic
+    :color = !light_text
+    &:after
+      :content " ..."
+    &:hover
+      :color black
+      :background #ffe
+      
 #index
   :font 85%/1.2 Arial, Helvetica, sans-serif
   a
@@ -93,10 +111,9 @@ table
   h1
     :padding .2em .5em .1em
     :background #ccc
-    :font = "small-caps 1.1em" !title_font
+    :font = "small-caps 1.2em" !title_font
     :color #333
     :border-bottom 1px solid gray
-    :border-top 1px solid #aaa
   ol
     :padding .4em .5em
     li
@@ -105,15 +122,16 @@ table
     :font-size 1.1em
     ol
       :padding 0
-    span.class
+    span.nodoc
       :display none
-    .class, a
+    span.nodoc, a
       :font-weight bold
     .parent
       :font-weight normal
   
 div.header
-  :padding .5em 12px
+  :font-size 80%
+  :padding .5em 2%
   :font-family Arial, Helvetica, sans-serif
   :border-bottom 1px solid silver
   .name
@@ -127,8 +145,6 @@ div.header
     :font-size 2.2em
   .paths, .last-update, .parent
     :color = !light_text
-  ol.paths
-    :padding-left .5em
   .last-update .datetime
     :color = !light_text - 30
   .parent
@@ -138,30 +154,37 @@ div.header
       :color = !light_text - 30
 
 #content
-  :padding 12px
+  :padding 12px 2%
   div.class &
     :position relative
-    :width 73%
+    :width 72%
   
   pre, .method .synopsis
-    :font = 15px !code_font
+    :font = !code_font
   pre
     :color black
     :background #eee
     :border 1px solid silver
     :padding 0 .5em .8em .5em
     :overflow auto
-  p, li
+  p, li, dl
     code, tt
-      :font = 15px !code_font
+      :font = !code_font
       :background #ffffe3
       :padding 2px 3px
+      :line-height 1.4
+  h1, h2, h3, h4, h5, h6
+    code, tt
+      :font-size 1.1em
+
+  #text
+    :position relative
   
   #description
     // :max-width 60em
     p
       :margin-top .5em
-    h1, h2, h3
+    h1, h2, h3, h4, h5, h6
       :font-family = !title_font
     h1
       :font-size 2.2em
@@ -170,21 +193,41 @@ div.header
       :padding-bottom .1em
     h2
       :font-size 1.8em
-      :color #0E3062
+      :color = !dark_blue_text
       :margin .8em 0 .3em 0
     h3
       :font-size 1.6em
       :margin .8em 0 .3em 0
       :color = !light_text
+    h4
+      :font-size 1.4em
+      :margin .8em 0 .3em 0
+    h5
+      :font-size 1.2em
+      :margin .8em 0 .3em 0
+      :color = !dark_blue_text
+    h6
+      :font-size 1.0em
+      :margin .8em 0 .3em 0
+      :color = !light_text
+
+  #description, .method .description
+    ul, ol
+      :margin .8em 0
+      :padding-left 1.5em
+    ol
+      :list-style decimal
+      li
+        :white-space wrap
 
 #method-list
   :position absolute
-  :top 12px
-  :right -31%
-  :width 27%
+  :top 0px
+  :right -33%
+  :width 28%
   :background #eee
   :border 1px solid silver
-  :padding .5em 1em
+  :padding .4em 1%
   :overflow hidden
   h2
     :font-size 1.3em
@@ -212,6 +255,10 @@ div.header
     :font = "small-caps 1.2em" !title_font
     :color #444
     :margin 1em 0 .2em 0
+  h4
+    :font = "1.1em" !title_font
+    :color = !dark_blue_text
+    :margin 1em 0 .2em 0
     
   .method
     :border 1px solid silver
@@ -221,7 +268,6 @@ div.header
       :color black
       :background silver
       :padding .2em 1em
-      :font-size 16px
       .name
         :font-weight bold
       a
@@ -236,7 +282,10 @@ div.header
       :font-size 85%
       :margin-left 1em
   .public-class
-    :background #ffd
+    :background #ffffe4
+  .public-instance .synopsis
+    :color #eee
+    :background = !light_link
 
 #content .method .source pre
   :background #262626

data/lib/hanna/template_helpers.rb

@@ -0,0 +1,66 @@
+require 'yaml'
+require 'cgi'
+
+module Hanna
+  module TemplateHelpers
+    protected
+
+    def link_to(text, url = nil, classname = nil)
+      class_attr = classname ? %[ class="#{classname}"] : ''
+      
+      if url
+        %[<a href="#{url}"#{class_attr}>#{text}</a>]
+      elsif classname
+        %[<span#{class_attr}>#{text}</span>]
+      else
+        text
+      end
+    end
+
+    def debug(text)
+      "<pre>#{h YAML::dump(text)}</pre>"
+    end
+
+    def h(html)
+      CGI::escapeHTML html
+    end
+
+    def methods_from_sections(sections)
+      sections.inject(Hash.new {|h, k| h[k] = []}) do |methods, section|
+        section['method_list'].each do |ml|
+          methods["#{ml['type']} #{ml['category']}".downcase].concat ml['methods']
+        end if section['method_list']
+        methods
+      end
+    end
+
+    def make_class_tree(entries)
+      entries.inject({}) do |tree, entry|
+        if entry['href']
+          leaf = entry['name'].split('::').inject(tree) do |branch, klass|
+            branch[klass] ||= {}
+          end
+          leaf['_href'] = entry['href']
+        end
+        tree
+      end
+    end
+
+    def render_class_tree(tree, parent = nil)
+      parent = parent + '::' if parent
+      tree.keys.sort.inject('') do |out, name|
+        unless name == '_href'
+          subtree = tree[name]
+          text = parent ? %[<span class="parent">#{parent}</span>#{name}] : name
+          out << '<li>'
+          out << (subtree['_href'] ? link_to(text, subtree['_href']) : %[<span class="nodoc">#{text}</span>])
+          if subtree.keys.size > 1
+            out << "\n<ol>" << render_class_tree(subtree, parent.to_s + name) << "\n</ol>"
+          end
+          out << '</li>'
+        end
+        out
+      end
+    end
+  end
+end

data/lib/hanna/template_page_patch.rb

@@ -1,7 +1,10 @@
-require 'yaml'
-require 'cgi'
+require 'hanna/template_helpers'
 
 RDoc::TemplatePage.class_eval do
+
+  include Hanna::TemplateHelpers
+  
+  # overwrite the original method
   def write_html_on(io, values)
     result = @templates.reverse.inject(nil) do |previous, template|
       case template
@@ -24,58 +27,6 @@ RDoc::TemplatePage.class_eval do
     raise
   end
 
-  protected
-
-  ### View helpers ###
-
-  def link_to(text, url = nil)
-    href(url, text)
-  end
-
-  def debug(text)
-    "<pre>#{h YAML::dump(text)}</pre>"
-  end
-
-  def h(html)
-    CGI::escapeHTML html
-  end
-
-  def methods_from_sections(sections)
-    sections.inject(Hash.new {|h, k| h[k] = []}) do |methods, section|
-      section['method_list'].each do |ml|
-        methods["#{ml['type']} #{ml['category']}".downcase].concat ml['methods']
-      end if section['method_list']
-      methods
-    end
-  end
-
-  def make_class_tree(entries)
-    entries.inject({}) do |tree, entry|
-      leaf = entry['name'].split('::').inject(tree) do |branch, klass|
-        branch[klass] ||= {}
-      end
-      leaf['_href'] = entry['href']
-      tree
-    end
-  end
-
-  def render_class_tree(tree, parent = nil)
-    parent = parent + '::' if parent
-    tree.keys.sort.inject('') do |out, name|
-      unless name == '_href'
-        subtree = tree[name]
-        text = parent ? "<span class='parent'>#{parent}</span>#{name}" : name
-        out << '<li>'
-        out << (subtree['_href'] ? link_to(text, subtree['_href']) : "<span class='class'>#{text}</span>")
-        if subtree.keys.size > 1
-          out << "\n<ol>" << render_class_tree(subtree, parent.to_s + name) << "\n</ol>"
-        end
-        out << '</li>'
-      end
-      out
-    end
-  end
-
   private
 
     def get_binding(values = nil)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mislav-hanna
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - "Mislav Marohni\xC4\x87"
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-05-02 00:00:00 -07:00
+date: 2008-05-03 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -19,7 +19,7 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        version: 2.0.0
+        version: 2.1.0
     version: 
 - !ruby/object:Gem::Dependency 
   name: haml
@@ -44,6 +44,7 @@ files:
 - bin
 - bin/hanna
 - lib
+- lib/hanna.rb
 - lib/hanna
 - lib/hanna/hanna.rb
 - lib/hanna/rdoc_patch.rb
@@ -57,6 +58,7 @@ files:
 - lib/hanna/template_files/page.haml
 - lib/hanna/template_files/sections.haml
 - lib/hanna/template_files/styles.sass
+- lib/hanna/template_helpers.rb
 - lib/hanna/template_page_patch.rb
 has_rdoc: false
 homepage: http://github.com/mislav/hanna
@@ -80,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.0.1
+rubygems_version: 1.2.0
 signing_key: 
 specification_version: 2
 summary: An RDoc template that rocks