hanna 0.1.12 → 1.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '079ac57437e1a0f17ae7a0279551cd6cedd63226d89525bd083bd6efb1dfaf7a'
+  data.tar.gz: 678ead6e236b87db78ccd70926f1ecd8258da4edc1125146eb46b6db6f8fc6a6
+SHA512:
+  metadata.gz: 45a89b66830d20ef83807ec53435bd0bf4c3d7997472ac8c2443efad186f1a251ea4efc6f49830e4cad0c96b7d04b62d083be6b7364dcb220060548e89495bf9
+  data.tar.gz: 608848deaf4abd6b421e122f1428ab5b9c4778513cebbe4770dbbf491e3c953c8913b33cd0552bc97a9943f9ca4a0a209005b0dfca94f20bf038a332b534a4f4

data/CHANGELOG

@@ -0,0 +1,113 @@
+# 1.5.0 (2023-08-10)
+
+* Rename back to hanna, after mislav granted access to the name (jeremyevans)
+
+# 1.4.0 (2023-01-10)
+
+* Improve style for mobile devices (janko) (#18, #19)
+
+# 1.3.0 (2022-06-27)
+
+* Use details/summary for class index (jeremyevans)
+
+* Optimize render_class_tree, and avoid creation of O(n^2) regexps (jeremyevans)
+
+* Use target="_top" for https links as well as http links (jeremyevans)
+
+# 1.2.0 (2021-12-23)
+
+* Remove dependency on haml, by switching to stdlib erb (jeremyevans)
+
+* Remove use of prototype.js for the method index, switching to plain javascript (jeremyevans)
+
+# 1.1.0 (2021-12-15)
+
+* Remove dependency on sass, by converting the stylesheet to CSS (jeremyevans)
+
+* Avoid Ruby verbose mode warnings (jeremyevans)
+
+# 1.0.4 (2020-06-24)
+
+* Avoid whitespace between method name and argument list (jeremyevans)
+
+# 1.0.3 (2018-02-15)
+
+* Avoid using deprecated sass color operators (jeremyevans)
+
+# 1.0.2 (2017-07-01)
+
+* Handle documenting BasicObject (jeremyevans)
+
+# 1.0.1 (2016-10-12)
+
+* Remove unneeded and harmful target="docwin" from links (jeremyevans)
+
+# 1.0.0 (2016-09-21)
+
+* Support haml 4+ and rdoc 5+ (jeremyevans)
+
+* Remove no longer needed override of parseable? in rdoc (jeremyevans)
+
+# 0.4.2 (2014-11-26)
+
+* Use ruby's built-in syntax parser instead of parser gem to check for valid syntax (jeremyevans)
+
+# 0.4.1 (2014-08-29)
+
+* Update syntax highlighting color for comments and strings (jeremyevans)
+
+# 0.4.0 (2014-08-19)
+
+* Add parser as a dependency for checking for valid Ruby syntax (jeremyevans)
+
+* Use table instead of dl for better styling of label/note lists (jeremyevans)
+
+* Syntax highlight ruby code blocks, not just method source (jeremyevans)
+
+# 0.3.0 (2014-06-18)
+
+* Show superclass instead of parent for classes (Quintus, jeremyevans)
+
+* Add support for RDoc 4 (Atsushi Nagase, jeremyevans)
+
+# 0.2.7 (2013-03-23)
+
+* Remove duplicate entries from method index (jeremyevans)
+
+* Fix attribute links (jeremyevans)
+
+# 0.2.6 (2013-03-01)
+
+* Fix homepage in gem (erikh)
+
+# 0.2.5 (2013-03-01)
+
+* Restrict rdoc version in gem to ~> 3.1, since the gem doesn't work with RDoc 4 (jeremyevans)
+
+# 0.2.4 (2011-07-24)
+
+* Respect markup in section comments (jeremyevans)
+
+* Fix class/singleton attribute anchors (jeremyevans)
+
+* Work with RDoc 3.8+ (jeremyevans)
+
+* Support RDoc sections (jeremyevans)
+
+* Automatically link classes, modules, included modules, and attributes (jeremyevans)
+
+# 0.2.3 (2011-05-12)
+
+* Sort method, aliases, and attribute lists (jeremyevans)
+
+# 0.2.2 (2010-12-28)
+
+* Work with RDoc 3.1+ (erikh)
+
+# 0.2.1 (2010-12-23)
+
+* Rename internal files to hanna-nouveau (erikh)
+
+# 0.2.0 (2010-12-23)
+
+* Initial release

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Mislav Marohnić
+Copyright (c) 2010, 2011 Erik Hollensbe
+Copyright (c) 2011-2023 Jeremy Evans
+
+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/README.rdoc

@@ -0,0 +1,63 @@
+= Hanna
+
+Hanna is an RDoc generator built with simplicity, beauty
+and ease of browsing in mind.
+
+== Installation
+
+    gem install hanna
+
+== Usage
+
+    rdoc -o doc -f hanna lib
+
+An alternative is to set the `RDOCOPT` environment variable:
+
+    RDOCOPT="-f hanna"
+
+This will make RDoc always use hanna unless it is explicitly overridden.
+
+== Integrating with RubyGems
+
+If you put the following line in your .gemrc, this will make
+RubyGems use Hanna for all rdoc generation:
+
+    rdoc: -f hanna
+
+After doing this, if you wish to have documentation for all your installed gems
+to be formatted in hanna:
+
+    gem rdoc --all --overwrite
+
+== Rake task
+
+For repeated generation of API docs, you can set up a Rake task. Set
+hanna as the RDoc generator:
+
+    require 'rdoc/task'
+    RDoc::Task.new do |rdoc|
+      rdoc.generator = 'hanna'
+    end
+
+== Modification to RDoc
+
+Hanna makes a small modification to RDoc to generate more
+friendly documentation.  It changes label lists to use a table
+instead of a description list, since it is very difficult to
+get visually appealing styling for description lists without
+cutting corners (like using fixed widths).
+
+== Contributors
+
+The Hanna template was created by {Mislav}[http://mislav.uniqpath.com/] and
+since then has seen contributions from:
+
+1. {Tony Strauss}[https://github.com/DesigningPatterns], who participated from
+   the early start and made tons of fixes and enhancements to the template.
+2. {Michael Granger}[https://github.com/ged] who maintained the original RDoc template.
+3. {Hongli Lai}[https://blog.phusion.nl/] with the search filter for methods.
+4. {Erik Hollensbe}[https://github.com/erikh] a serious refactoring and up to
+   date with RDoc 2.5.x and 3.x, now named 'hanna-nouveau'.
+5. {James Tucker}[https://github.com/raggi] minor cleanups and RubyGems integration
+6. {Jeremy Evans}[https://github.com/jeremyevans] RDoc 4+ support, switch from
+   haml/sass to erb, maintenance since 2014.

data/lib/hanna/template_files/class_index.erb

@@ -0,0 +1,4 @@
+<h1><%=h values[:list_title] %></h1>
+<div class='classes' id='index-entries'>
+<%= render_class_tree(values[:classes].select{|x| x.full_name !~ /::/}) %>
+</div>

data/lib/hanna/template_files/file_index.erb

@@ -0,0 +1,9 @@
+<h1>File Index</h1><% any_hidden = false %>
+<ol class='files' id='index-entries'>
+<% values[:files].each do |file|
+    hide = file.name =~ /\.rb$/
+    any_hidden = true if hide %><li<%= " class='other'" if hide %>><%= link_to(file.name, file.path) %></li>
+<% end %><% if any_hidden %><li>
+<a class='show' href='#' onclick='this.parentNode.parentNode.className += &quot; expanded&quot;; this.parentNode.removeChild(this); return false'>show all</a>
+</li><% end %>
+</ol>

data/lib/hanna/template_files/index.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">
+<html lang='en' xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>
+<head>
+<title><%=h @options.title %></title>
+<meta content='text/html; charset=<%=h @options.charset %>' http-equiv='Content-Type'>
+</head>
+<frameset border='1' bordercolor='gray' cols='20%, *' frameborder='1'>
+<frameset rows='15%, 35%, 50%'>
+<frame name='Files' src='fr_file_index.html' title='Files'>
+<frame name='Classes' src='fr_class_index.html'>
+<frame name='Methods' src='fr_method_index.html'>
+</frameset>
+<frame name='docwin' src='<%=h @main_page_uri %>'></frame>
+</frameset>
+</html>

data/lib/hanna/template_files/layout.erb

@@ -0,0 +1,35 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"><% values = values[:values]; index = values[:list_title] %>
+<html lang='en'>
+<head>
+<title><%= h(values[:title]) if values[:title] %></title>
+<meta name='viewport' content='width=device-width, initial-scale=1'>
+<meta content='text/html; charset=<%=h @options.charset %>' http-equiv='Content-Type'>
+<link href='<%=h values[:stylesheet] %>' media='screen' rel='stylesheet' type='text/css'>
+<% if index %><base target='docwin'>
+<% else %><script type='text/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>')
+</script>
+<% end %></head>
+<body class='<%= index ? 'list' : 'page' %>'>
+<% if index %><div id='index'><%= yield %></div>
+<% else %><div class='<%= values[:classmod] ? 'class' : 'file' %>' id='wrapper'>
+<%= yield %>
+<div id='footer-push'></div>
+</div>
+<div id='footer'>
+<a href="https://github.com/jeremyevans/hanna"><strong>Hanna</strong> RDoc template</a>
+</div>
+<% end %></body>
+</html>

data/lib/hanna/template_files/method_index.erb

@@ -0,0 +1,11 @@
+<h1><%=h values[:list_title] %></h1>
+<form id='search_form'>
+<input autocomplete='off' class='untouched' id='search' placeholder='Enter search terms...' type='text'>
+<span class='clear_button' id='clear_button'>
+x
+</span>
+</form>
+<ol class='methods' id='index-entries'>
+<% (values[:attributes] + values[:methods]).uniq.each do |entry| %><li><%= link_to_method(entry, [classfile(entry.parent), entry.aref].join('#')) %></li>
+<% end %></ol>
+<script src='method_search.js' type='text/javascript'></script>

data/lib/hanna/template_files/method_list.erb

@@ -0,0 +1,58 @@
+<%
+values = values[:values] if values[:values]
+entry = values[:entry]
+sections = values[:sections].keys if values.has_key?(:sections)
+methods = entry.method_list + entry.attributes
+unless methods.empty? %><div id='method-list'>
+<h2>Methods</h2>
+<% %w[attr attr_accessor attr_reader attr_writer class instance].each do |type|
+    (RDoc::VISIBILITIES rescue RDoc::Context::VISIBILITIES).each do |vis|
+      list = methods.reject { |x| x.respond_to?(:is_alias_for) && x.is_alias_for }.select { |x| x.visibility == vis && x.type == type.to_s }.sort
+      next if list.empty?
+      type_result = ""
+      if type =~ /^attr_/
+        type_result += type.sub(/^attr_/, '').capitalize
+      else
+        type_result += type.capitalize
+      end
+      type_result = "#{vis.to_s.capitalize} #{type_result}"
+%><h3><%=h type_result %></h3>
+<ol>
+<%
+      list.each do |method|
+        if method.respond_to?(:aref)
+          if method.name.to_s.empty? && method.call_seq %><li><%= link_to(method.call_seq.gsub(/<br\s*\/?>/, "").split(/[\r\n]+/).map{ |s| s.split(/([({]+|\[\{|\s+(#?=>|&rarr;)\s+)/).first.sub(/^[A-Za-z0-9_:]+\./, "").sub(/\s+=\s+.*/, "=").strip }.uniq.join("<br />\n"), '#' + method.aref) %></li>
+<%        else %><li><%= link_to(method.name, '#' + method.aref) %></li>
+<%        end
+        elsif method.respond_to?(:html_name) %><li><%= link_to(method.name, "#method-#{method.html_name}") %></li>
+<%      else %><li><%=h method.name %></li>
+<%      end
+      end %></ol>
+<%  end
+  end %></div>
+<%
+end
+if entry.requires or sections or entry.includes %><div id='context'>
+<% unless entry.requires.empty? %><div id='requires'>
+<h2>Required files</h2>
+<ol>
+<% entry.requires.each do |req| %><li><%=h req.name %></li>
+<% end %></ol>
+</div>
+<% end
+   if sections && (sections.length > 1 || sections.first.title.to_s != '')
+%><div id='contents'>
+<h2>Contents</h2>
+<ol>
+<% sections.sort_by{|s| s.title.to_s}.each do |section| %><li><%= link_to(section.title, "##{section.aref}") %></li>
+<% end %></ol>
+</div>
+<% end
+   unless entry.includes.empty?
+%><div id='includes'>
+<h2>Included modules</h2>
+<ol>
+<% entry.includes.each do |inc| %><li><%= (mod = inc.module).is_a?(String) ? h(inc.name) : link_to(inc.name, entry.aref_to(mod.path)) %></li>
+<% end %></ol>
+</div>
+<% end %></div><% end %>

data/lib/hanna/template_files/method_search.js

@@ -1,63 +1,45 @@
-$(document).observe('dom:loaded', function() {
-	// Setup search-during-typing.
-	new Form.Element.Observer('search', 0.3, function(element, value) {
-		performSearch();
-	});
-	
-	// Remove the default search box value when the user puts the focus on
-	// the search box for the first time.
-	var search_box = $('search');
-	if ($F('search') == 'Enter search terms...') {
-		search_box.observe('focus', function() {
-			if (search_box.hasClassName('untouched')) {
-				search_box.removeClassName('untouched');
-				search_box.value = '';
-			}
-		});
-	} else {
-		search_box.removeClassName('untouched');
-	}
-	
-	search_box.insert({
-	  after: new Element('span', { 'class': 'clear_button' }).update('x').observe('click', function(e) {
-	    e.stopPropagation()
-  	  search_box.setValue('')
-  	  search_box.focus()
-  	})
-  })
-});
-
-function searchInIndex(query) {
-	var i;
-	var results = [];
-	query = query.toLowerCase();
-	for (i = 0; i < search_index.length; i++) {
-		if (search_index[i].method.indexOf(query) != -1) {
-			results.push(search_index[i]);
-		}
-	}
-	return results;
-}
+var search_box = document.getElementById('search');
+var search_timeout;
+var search_value = search_box.value;
 
-function buildHtmlForResults(results) {
-	var html = "";
-	var i;
-	for (i = 0; i < results.length; i++) {
-		html += '<li>' + results[i].html + '</li>';
-	}
-	return html;
-}
+function performSearch(e) {
+  if (e) {
+    e.preventDefault();
+  }
+  if (search.value === search_value) {
+    return;
+  }
+  search_value = search_box.value;
 
-function performSearch() {
-	var query = $F('search');
-	if (query == '') {
-		$('index-entries').show();
-		$('search-results').hide();
+	if (search_value == '') {
+    document.querySelectorAll("#index-entries li.hide").forEach(elem => {
+      elem.classList.remove('hide');
+    });
 	} else {
-		var results = searchInIndex(query);
-		$('search-results').update(buildHtmlForResults(results));
-		$('index-entries').hide();
-		$('search-results').show();
-	}
-	return false;
+    document.querySelectorAll("#index-entries span.method_name").forEach(elem => {
+      var value = elem.getAttribute('value');
+      var li_classes = elem.parentElement.parentElement.classList;
+      if (value && value.includes(search_value)) {
+        li_classes.remove('hide');
+      } else {
+        li_classes.add('hide');
+      }
+    });
+  }
 }
+
+document.getElementById('search_form').onsubmit = performSearch;
+
+search.oninput = function(e) {
+  if (search_timeout) {
+    clearTimeout(search_timeout);
+  }
+  search_timeout = setTimeout(performSearch, 300);
+};
+
+document.getElementById('clear_button').onclick = function(e) {
+  e.stopPropagation();
+  search_box.value = '';
+  performSearch();
+  search_box.focus();
+};

data/lib/hanna/template_files/page.erb

@@ -0,0 +1,48 @@
+<%
+values = values[:values] if values[:values]
+file_page = !values[:classmod]
+title_in_description = values[:entry].description && values[:entry].description =~ /^\s*<h1>/m
+%><div class='header'>
+<%
+title = if file_page
+  h(values[:file].name)
+else
+  "<span class='type'>#{values[:classmod]}</span>\n#{h values[:entry].full_name}"
+end
+
+   if title_in_description %><div class='name'><%= title %></div>
+<% else %><h1 class='name'><%= title %>
+</h1>
+<% end
+
+   if file_page %><div class='paths'>
+<%=h values[:file].relative_name %>
+</div>
+<% else %><ol class='paths'>
+<%   values[:entry].in_files.each_with_index do |file, index| %><li<%= " class='other'" if index > 0 %>>
+<%= link_to(file.full_name, Pathname.new(file.path).relative_path_from(Pathname.new(values[:entry].path).dirname)) %>
+</li>
+<%   end
+     if values[:entry].in_files.size > 1 %><li>
+<a class='show' href='#' onclick='this.parentNode.parentNode.className += &quot; expanded&quot;; this.parentNode.removeChild(this); return false'>show all</a>
+</li>
+<%   end %></ol>
+<% end
+
+   if !file_page && values[:entry].type == "class" %><div class='parent'>
+Superclass:
+<strong><%= (values[:entry].superclass.kind_of?(String) || !values[:entry].superclass) ? h(values[:entry].superclass) : link_to(values[:entry].superclass.name, Pathname.new(class_dir) + Pathname.new(values[:entry].superclass.path).relative_path_from(Pathname.new values[:entry].path)) %></strong>
+</div>
+<% end
+
+   if values[:entry].respond_to?(:last_modified) and values[:entry].last_modified %><div class='last-update'>
+Last Update:
+<span class='datetime'><%=h values[:entry].last_modified %></span>
+</div>
+<% end %></div>
+<div id='content'>
+<div id='text'>
+<% if values[:description] %><div id='description'><%= frame_link(values[:description]) %></div>
+<% end %><%= frame_link(block.call) %>
+</div>
+</div>

data/lib/hanna/template_files/sections.erb

@@ -0,0 +1,92 @@
+<%
+values = values[:values] if values[:values]
+unless values[:entry].classes_and_modules.empty? %><div id='class-list'>
+<h2>Classes and Modules</h2>
+<ol>
+<%   (values[:entry].modules.sort + values[:entry].classes.sort).each do |mod| %><li><%= link_to(mod.full_name, values[:entry].aref_to(mod.path)) %></li>
+<%   end %></ol>
+</div>
+<% end
+
+values[:sections].sort_by{|s, h| s.title.to_s}.each do |section, h|
+  constants, attributes, alias_types, method_types = h.values_at(:constants, :attributes, :alias_types, :method_types)
+%><div id='section'>
+<% if section.title.to_s != '' %><h2>
+<a name='<%=h section.aref %>'><%=h section.title %></a>
+<% if section.comment %><div class='section-comment'><%= section.description %></div>
+<% end %></h2> 
+<% end
+   unless constants.empty? %><div id='constants-list'>
+<h2>Constants</h2>
+<div class='name-list'>
+<table summary='Constants'>
+<%   constants.each do |const| %><tr class='top-aligned-row context-row'>
+<td class='context-item-name'><%= const.name %></td>
+<td>=</td>
+<td class='context-item-value'><%= const.value %></td>
+<%     if const.description %><td>&nbsp;</td>
+<td class='context-item-desc'><%= const.description %></td>
+<%     end %></tr>
+<%   end %></table>
+</div>
+</div>
+<% end
+   unless alias_types.empty?
+     alias_types.each do |type, aliases|
+     %><div id='aliases-list'>
+<h2><%= type %> Aliases</h2>
+<div class='name-list'>
+<table summary='<%= type %> Aliases'>
+<%     aliases.each do |alia| %><tr class='top-aligned-row context-row'>
+<td class='context-item-name'><%= alia.name %></td>
+<td>-&gt;</td>
+<td class='context-item-value'><%= link_to(alia.is_alias_for.name, "##{alia.is_alias_for.aref}") %></td>
+<%       unless alia.description.empty? %><td class='context-item-desc'><%= alia.description %></td>
+<%       end %></tr>
+<%     end %></table>
+</div>
+</div>
+<%   end
+   end
+   unless attributes.empty? %><div id='attribute-list'>
+<h2 class='section-bar'>Attributes</h2>
+<div class='name-list'>
+<table>
+<%   attributes.each do |attrib| %><tr class='top-aligned-row context-row'>
+<td class='context-item-name'>
+<a name='<%=h attrib.aref %>'><%= attrib.name %></a>
+</td>
+<td class='context-item-value'><%= attrib.rw ? "[#{attrib.rw}]" : '&nbsp;' %></td>
+<td class='context-item-desc'><%= attrib.description %></td>
+</tr>
+<%   end %></table>
+</div>
+</div>
+<% end
+   unless method_types.empty? %><div id='methods'>
+<%   method_types.each do |type, list| next if list.empty? %><h2><%= type %> methods</h2>
+<%     list.each do |method| %><div class='method <%= "#{type.gsub(/\s+/, '-')}".downcase %>' id='method-<%= method.aref %>'>
+<a name='<%= method.aref %>'></a>
+<div class='synopsis'>
+<%       if method.call_seq %><span class='name'>
+<%         method.call_seq.split(/\r?\n/).each do |seq| %><div><%= seq %></div>
+</span>
+<%         end
+         else %><span class='name'><%= method.name %></span><span class='arguments'><%= method.params %></span>
+
+<%       end %></div>
+<%       if method.description %><div class='description'>
+<%= method.description %>
+</div>
+<%       end
+         if method.markup_code
+           name = "#{method.aref}-source" %><div class='source'>
+<a class='source-toggle' href='#' onclick='toggleCode(&#39;<%= name %>&#39;); return false'>
+[show source]
+</a>
+<pre id='<%= name %>'><%= method.markup_code %></pre>
+</div>
+<%       end %></div>
+<%     end 
+     end %></div>
+<% end %></div><% end %>