voloko-sdoc 0.1.2 → 0.1.3

data/rdoc/lib/rdoc/generator/ri.rb

@@ -0,0 +1,230 @@
+require 'rdoc/generator'
+require 'rdoc/markup/to_flow'
+
+require 'rdoc/ri/cache'
+require 'rdoc/ri/reader'
+require 'rdoc/ri/writer'
+require 'rdoc/ri/descriptions'
+
+class RDoc::Generator::RI
+
+  RDoc::RDoc.add_generator self
+
+  ##
+  # Generator may need to return specific subclasses depending on the
+  # options they are passed. Because of this we create them using a factory
+
+  def self.for(options)
+    new(options)
+  end
+
+  ##
+  # Set up a new ri generator
+
+  def initialize(options) #:not-new:
+    @options   = options
+    @ri_writer = RDoc::RI::Writer.new "."
+    @markup    = RDoc::Markup.new
+    @to_flow   = RDoc::Markup::ToFlow.new
+
+    @generated = {}
+  end
+
+  ##
+  # Build the initial indices and output objects based on an array of
+  # TopLevel objects containing the extracted information.
+
+  def generate(top_levels)
+    RDoc::TopLevel.all_classes_and_modules.each do |cls|
+      process_class cls
+    end
+  end
+
+  def process_class(from_class)
+    generate_class_info(from_class)
+
+    # now recurse into this class' constituent classes
+    from_class.each_classmodule do |mod|
+      process_class(mod)
+    end
+  end
+
+  def generate_class_info(cls)
+    case cls
+    when RDoc::NormalModule then
+      cls_desc = RDoc::RI::ModuleDescription.new
+    else
+      cls_desc = RDoc::RI::ClassDescription.new
+      superclass = cls.superclass
+      superclass = superclass.full_name unless String === superclass
+      cls_desc.superclass = superclass
+    end
+
+    cls_desc.name        = cls.name
+    cls_desc.full_name   = cls.full_name
+    cls_desc.comment     = markup(cls.comment)
+
+    cls_desc.attributes = cls.attributes.sort.map do |a|
+      RDoc::RI::Attribute.new(a.name, a.rw, markup(a.comment))
+    end
+
+    cls_desc.constants = cls.constants.map do |c|
+      RDoc::RI::Constant.new(c.name, c.value, markup(c.comment))
+    end
+
+    cls_desc.includes = cls.includes.map do |i|
+      RDoc::RI::IncludedModule.new(i.name)
+    end
+
+    class_methods, instance_methods = method_list(cls)
+
+    cls_desc.class_methods = class_methods.map do |m|
+      RDoc::RI::MethodSummary.new(m.name)
+    end
+
+    cls_desc.instance_methods = instance_methods.map do |m|
+      RDoc::RI::MethodSummary.new(m.name)
+    end
+
+    update_or_replace(cls_desc)
+
+    class_methods.each do |m|
+      generate_method_info(cls_desc, m)
+    end
+
+    instance_methods.each do |m|
+      generate_method_info(cls_desc, m)
+    end
+  end
+
+  def generate_method_info(cls_desc, method)
+    meth_desc = RDoc::RI::MethodDescription.new
+    meth_desc.name = method.name
+    meth_desc.full_name = cls_desc.full_name
+    if method.singleton
+      meth_desc.full_name += "::"
+    else
+      meth_desc.full_name += "#"
+    end
+    meth_desc.full_name << method.name
+
+    meth_desc.comment = markup(method.comment)
+    meth_desc.params = params_of(method)
+    meth_desc.visibility = method.visibility.to_s
+    meth_desc.is_singleton = method.singleton
+    meth_desc.block_params = method.block_params
+
+    meth_desc.aliases = method.aliases.map do |a|
+      RDoc::RI::AliasName.new(a.name)
+    end
+
+    @ri_writer.add_method(cls_desc, meth_desc)
+  end
+
+  private
+
+  ##
+  # Returns a list of class and instance methods that we'll be documenting
+
+  def method_list(cls)
+    list = cls.method_list
+    unless @options.show_all
+      list = list.find_all do |m|
+        m.visibility == :public || m.visibility == :protected || m.force_documentation
+      end
+    end
+
+    c = []
+    i = []
+    list.sort.each do |m|
+      if m.singleton
+        c << m
+      else
+        i << m
+      end
+    end
+    return c,i
+  end
+
+  def params_of(method)
+    if method.call_seq
+      method.call_seq
+    else
+      params = method.params || ""
+
+      p = params.gsub(/\s*\#.*/, '')
+      p = p.tr("\n", " ").squeeze(" ")
+      p = "(" + p + ")" unless p[0] == ?(
+
+      if (block = method.block_params)
+        block.gsub!(/\s*\#.*/, '')
+        block = block.tr("\n", " ").squeeze(" ")
+        if block[0] == ?(
+          block.sub!(/^\(/, '').sub!(/\)/, '')
+        end
+        p << " {|#{block.strip}| ...}"
+      end
+      p
+    end
+  end
+
+  def markup(comment)
+    return nil if !comment || comment.empty?
+
+    # Convert leading comment markers to spaces, but only
+    # if all non-blank lines have them
+
+    if comment =~ /^(?>\s*)[^\#]/
+      content = comment
+    else
+      content = comment.gsub(/^\s*(#+)/)  { $1.tr('#',' ') }
+    end
+    @markup.convert(content, @to_flow)
+  end
+
+  ##
+  # By default we replace existing classes with the same name. If the
+  # --merge option was given, we instead merge this definition into an
+  # existing class. We add our methods, aliases, etc to that class, but do
+  # not change the class's description.
+
+  def update_or_replace(cls_desc)
+    old_cls = nil
+
+    if @options.merge
+      rdr = RDoc::RI::Reader.new RDoc::RI::Cache.new(@options.op_dir)
+
+      namespace = rdr.top_level_namespace
+      namespace = rdr.lookup_namespace_in(cls_desc.name, namespace)
+      if namespace.empty?
+        $stderr.puts "You asked me to merge this source into existing "
+        $stderr.puts "documentation. This file references a class or "
+        $stderr.puts "module called #{cls_desc.name} which I don't"
+        $stderr.puts "have existing documentation for."
+        $stderr.puts
+        $stderr.puts "Perhaps you need to generate its documentation first"
+        exit 1
+      else
+        old_cls = namespace[0]
+      end
+    end
+
+    prev_cls = @generated[cls_desc.full_name]
+
+    if old_cls and not prev_cls then
+      old_desc = rdr.get_class old_cls
+      cls_desc.merge_in old_desc
+    end
+
+    if prev_cls then
+      cls_desc.merge_in prev_cls
+    end
+
+    @generated[cls_desc.full_name] = cls_desc
+
+    @ri_writer.remove_class cls_desc
+    @ri_writer.add_class cls_desc
+  end
+
+end
+

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

@@ -0,0 +1,281 @@
+<?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=<%= @options.charset %>" http-equiv="Content-Type" />
+
+	<title><%= klass.type.capitalize %>: <%= klass.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>
+
+</head>
+<body class="<%= klass.type %>">
+
+	<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>
+					<% klass.in_files.each do |tl| %>
+						<li><a href="<%= rel_prefix %>/<%= h tl.path %>.html?TB_iframe=true&amp;height=550&amp;width=785"
+							class="thickbox" title="<%= h tl.absolute_name %>"><%= h tl.absolute_name %></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 klass.type == 'class' %>
+			<div id="parent-class-section" class="section">
+				<h3 class="section-header">Parent</h3>
+				<% unless String === klass.superclass %>
+				<p class="link"><a href="<%= klass.aref_to klass.superclass.path %>"><%= klass.superclass.full_name %></a></p>
+				<% else %>
+				<p class="link"><%= klass.superclass %></p>
+				<% end %>
+			</div>
+			<% end %>
+
+			<!-- Namespace Contents -->
+			<% unless klass.classes_and_modules.empty? %>
+			<div id="namespace-list-section" class="section">
+				<h3 class="section-header">Namespace</h3>
+				<ul class="link-list">
+					<% (klass.modules.sort + klass.classes.sort).each do |mod| %>
+					<li><span class="type"><%= mod.type.upcase %></span> <a href="<%= klass.aref_to mod.path %>"><%= mod.full_name %></a></li>
+					<% end %>
+				</ul>
+			</div>
+			<% end %>
+
+			<!-- Method Quickref -->
+			<% unless klass.method_list.empty? %>
+			<div id="method-list-section" class="section">
+				<h3 class="section-header">Methods</h3>
+				<ul class="link-list">
+					<% klass.each_method do |meth| %>
+					<li><a href="#<%= meth.aref %>"><%= meth.singleton ? '::' : '#' %><%= meth.name %></a></li>
+					<% end %>
+				</ul>
+			</div>
+			<% end %>
+
+			<!-- Included Modules -->
+			<% unless klass.includes.empty? %>
+			<div id="includes-section" class="section">
+				<h3 class="section-header">Included Modules</h3>
+				<ul class="link-list">
+				<% klass.each_include do |inc| %>
+				<% unless String === inc.module %>
+					<li><a class="include" href="<%= klass.aref_to inc.module.path %>"><%= inc.module.full_name %></a></li>
+				<% else %>
+					<li><span class="include"><%= inc.name %></span></li>
+				<% end %>
+				<% end %>
+				</ul>
+			</div>
+			<% end %>
+		</div>
+
+		<div id="project-metadata">
+			<% simple_files = @files.select {|tl| tl.parser == RDoc::Parser::Simple } %>
+			<% unless simple_files.empty? then %>
+			<div id="fileindex-section" class="section project-section">
+				<h3 class="section-header">Files</h3>
+				<ul>
+				<% simple_files.each do |file| %>
+					<li class="file"><a href="<%= rel_prefix %>/<%= file.path %>"><%= h file.base_name %></a></li>
+				<% end %>
+				</ul>
+			</div>
+			<% end %>
+
+			<div id="classindex-section" class="section project-section">
+				<h3 class="section-header">Class Index
+					<span class="search-toggle"><img src="<%= rel_prefix %>/images/find.png"
+						height="16" width="16" alt="[+]"
+						title="show/hide quicksearch" /></span></h3>
+				<form action="#" method="get" accept-charset="utf-8" class="initially-hidden">
+				<fieldset>
+					<legend>Quicksearch</legend>
+					<input type="text" name="quicksearch" value=""
+						class="quicksearch-field" />
+				</fieldset>
+				</form>
+
+				<ul class="link-list">
+				<% @modsort.each do |index_klass| %>
+					<li><a href="<%= rel_prefix %>/<%= index_klass.path %>"><%= index_klass.full_name %></a></li>
+				<% end %>
+				</ul>
+				<div id="no-class-search-results" style="display: none;">No matching classes.</div>
+			</div>
+
+			<% if $DEBUG_RDOC %>
+			<div id="debugging-toggle"><img src="<%= rel_prefix %>/images/bug.png"
+				alt="toggle debugging" height="16" width="16" /></div>
+			<% end %>
+		</div>
+	</div>
+
+	<div id="documentation">
+		<h1 class="<%= klass.type %>"><%= klass.full_name %></h1>
+
+		<div id="description">
+			<%= klass.description %>
+		</div>
+
+		<!-- Constants -->
+		<% unless klass.constants.empty? %>
+		<div id="constants-list" class="section">
+			<h3 class="section-header">Constants</h3>
+			<dl>
+			<% klass.each_constant do |const| %>
+				<dt><a name="<%= const.name %>"><%= const.name %></a></dt>
+				<% if const.comment %>
+				<dd class="description"><%= const.description.strip %></dd>
+				<% else %>
+				<dd class="description missing-docs">(Not documented)</dd>
+				<% end %>
+			<% end %>
+			</dl>
+		</div>
+		<% end %>
+
+		<!-- Attributes -->
+		<% unless klass.attributes.empty? %>
+		<div id="attribute-method-details" class="method-section section">
+			<h3 class="section-header">Attributes</h3>
+
+			<% klass.each_attribute do |attrib| %>
+			<div id="<%= attrib.html_name %>-attribute-method" class="method-detail">
+				<a name="<%= h attrib.name %>"></a>
+				<% if attrib.rw =~ /w/i %>
+				<a name="<%= h 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.comment %>
+				<%= attrib.description.strip %>
+				<% else %>
+				<p class="missing-docs">(Not documented)</p>
+				<% end %>
+				</div>
+			</div>
+			<% end %>
+		</div>
+		<% end %>
+
+		<!-- Methods -->
+		<% klass.methods_by_type.each do |type, visibilities|
+			 next if visibilities.empty?
+			 visibilities.each do |visibility, methods|
+				 next if methods.empty? %>
+		<div id="<%= visibility %>-<%= type %>-method-details" class="method-section section">
+			<h3 class="section-header"><%= visibility.to_s.capitalize %> <%= type.capitalize %> Methods</h3>
+
+		<% methods.each do |method| %>
+			<div id="<%= method.html_name %>-method" class="method-detail <%= method.is_alias_for ? "method-alias" : '' %>">
+				<a name="<%= h method.aref %>"></a>
+
+				<div class="method-heading">
+				<% if method.call_seq %>
+					<span class="method-callseq"><%= method.call_seq.strip.gsub(/->/, '&rarr;').gsub( /^\w.*?\./m, '') %></span>
+					<span class="method-click-advice">click to toggle source</span>
+				<% else %>
+					<span class="method-name"><%= h method.name %></span><span
+						class="method-args"><%= method.params %></span>
+					<span class="method-click-advice">click to toggle source</span>
+				<% end %>
+				</div>
+
+				<div class="method-description">
+					<% if method.comment %>
+					<%= method.description.strip %>
+					<% else %>
+					<p class="missing-docs">(Not documented)</p>
+					<% end %>
+
+					<% if method.token_stream %>
+					<div class="method-source-code"
+						id="<%= method.html_name %>-source">
+<pre>
+<%= method.markup_code %>
+</pre>
+					</div>
+					<% end %>
+				</div>
+
+				<% unless method.aliases.empty? %>
+				<div class="aliases">
+					Also aliased as: <%= method.aliases.map do |aka|
+						%{<a href="#{ klass.aref_to aka.path}">#{h aka.name}</a>}
+					end.join(", ") %>
+				</div>
+				<% end %>
+			</div>
+
+		<% end %>
+		</div>
+	<% end
+		 end %>
+
+	</div>
+
+
+	<div id="rdoc-debugging-section-dump" class="debugging-section">
+	<% if $DEBUG_RDOC
+			 require 'pp' %>
+<pre><%= h PP.pp(klass, _erbout) %></pre>
+		</div>
+	<% else %>
+		<p>Disabled; run with --debug to generate this.</p>
+	<% 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> <%= RDoc::Generator::Darkfish::VERSION %></small>.</p>
+	</div>
+
+</body>
+</html>
+

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

@@ -0,0 +1,112 @@
+<?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=<%= @options.charset %>" http-equiv="Content-Type" />
+
+	<title>File: <%= file.base_name %> [<%= @options.title %>]</title>
+
+	<link type="text/css" media="screen" href="<%= rel_prefix %>/rdoc.css" rel="stylesheet" />
+
+	<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>
+</head>
+
+<% if file.parser == RDoc::Parser::Simple %>
+<body class="file">
+  <div id="metadata">
+		<div id="project-metadata">
+			<% simple_files = @files.select { |f| f.parser == RDoc::Parser::Simple } %>
+			<% unless simple_files.empty? then %>
+			<div id="fileindex-section" class="section project-section">
+				<h3 class="section-header">Files</h3>
+				<ul>
+				<% simple_files.each do |f| %>
+					<li class="file"><a href="<%= rel_prefix %>/<%= f.path %>"><%= h f.base_name %></a></li>
+				<% end %>
+				</ul>
+			</div>
+			<% end %>
+
+			<div id="classindex-section" class="section project-section">
+				<h3 class="section-header">Class Index
+					<span class="search-toggle"><img src="<%= rel_prefix %>/images/find.png"
+						height="16" width="16" alt="[+]"
+						title="show/hide quicksearch" /></span></h3>
+				<form action="#" method="get" accept-charset="utf-8" class="initially-hidden">
+				<fieldset>
+					<legend>Quicksearch</legend>
+					<input type="text" name="quicksearch" value=""
+						class="quicksearch-field" />
+				</fieldset>
+				</form>
+
+				<ul class="link-list">
+				<% @modsort.each do |index_klass| %>
+					<li><a href="<%= rel_prefix %>/<%= index_klass.path %>"><%= index_klass.full_name %></a></li>
+				<% end %>
+				</ul>
+				<div id="no-class-search-results" style="display: none;">No matching classes.</div>
+			</div>
+
+			<% if $DEBUG_RDOC %>
+			<div id="debugging-toggle"><img src="<%= rel_prefix %>/images/bug.png"
+				alt="toggle debugging" height="16" width="16" /></div>
+			<% end %>
+		</div>
+	</div>
+
+	<div id="documentation">
+		<%= file.description %>
+	</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> <%= RDoc::Generator::Darkfish::VERSION %></small>.</p>
+	</div>
+</body>
+<% else %>
+<body class="file file-popup">
+	<div id="metadata">
+		<dl>
+			<dt class="modified-date">Last Modified</dt>
+			<dd class="modified-date"><%= file.last_modified %></dd>
+
+			<% if file.requires %>
+			<dt class="requires">Requires</dt>
+			<dd class="requires">
+				<ul>
+				<% file.requires.each do |require| %>
+					<li><%= require.name %></li>
+				<% end %>
+				</ul>
+			</dd>
+			<% end %>
+
+			<% if @options.webcvs %>
+			<dt class="scs-url">Trac URL</dt>
+			<dd class="scs-url"><a target="_top"
+				href="<%= file.cvs_url %>"><%= file.cvs_url %></a></dd>
+			<% end %>
+		</dl>
+
+		<% if file.comment %>
+		<div class="description">
+			<h2>Description</h2>
+			<%= file.description %>
+		</div>
+		<% end %>
+	</div>
+</body>
+<% end %>
+</html>
+