rdoc 3.9.5 → 3.10.pre.1

data/lib/rdoc/generator/json_index.rb

@@ -0,0 +1,240 @@
+require 'json'
+
+##
+# The JsonIndex generator is designed to complement an HTML generator and
+# produces a JSON search index.  This generator is derived from sdoc by
+# Vladimir Kolesnikov and contains verbatim code written by him.
+#
+# This generator is designed to be used with a regular HTML generator:
+#
+#   class RDoc::Generator::Darkfish
+#     def initialize options
+#       # ...
+#       @base_dir = Pathname.pwd.expand_path
+#
+#       @json_index = RDoc::Generator::JsonIndex.new self, options
+#     end
+#
+#     def generate top_levels
+#       # ...
+#       @json_index.generate top_levels
+#     end
+#   end
+#
+# == Index Format
+#
+# The index is output as a JSON file assigned to the global variable
+# +search_data+.  The structure is:
+#
+#   var search_data = {
+#     "index": {
+#       "searchIndex":
+#         ["a", "b", ...],
+#       "longSearchIndex":
+#         ["a", "a::b", ...],
+#       "info": [
+#         ["A", "A", "A.html", "", ""],
+#         ["B", "A::B", "A::B.html", "", ""],
+#         ...
+#       ]
+#     }
+#   }
+#
+# The same item is described across the +searchIndex+, +longSearchIndex+ and
+# +info+ fields.  The +searchIndex+ field contains the item's short name, the
+# +longSearchIndex+ field contains the full_name (when appropriate) and the
+# +info+ field contains the item's name, full_name, path, parameters and a
+# snippet of the item's comment.
+#
+# == LICENSE
+#
+# Copyright (c) 2009 Vladimir Kolesnikov
+#
+# 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.
+
+class RDoc::Generator::JsonIndex
+
+  include RDoc::Text
+
+  ##
+  # Where the search index lives in the generated output
+
+  SEARCH_INDEX_FILE = File.join 'js', 'search_index.js'
+
+  attr_reader :index # :nodoc:
+
+  ##
+  # Creates a new generator.  +parent_generator+ is used to determine the
+  # class_dir and file_dir of links in the output index.
+  #
+  # +options+ are the same options passed to the parent generator.
+
+  def initialize parent_generator, options
+    @parent_generator = parent_generator
+    @options = options
+
+    @template_dir = File.expand_path '../template/json_index', __FILE__
+    @base_dir = @parent_generator.base_dir
+
+    @classes = nil
+    @files   = nil
+    @index   = nil
+  end
+
+  ##
+  # Output progress information if debugging is enabled
+
+  def debug_msg *msg
+    return unless $DEBUG_RDOC
+    $stderr.puts(*msg)
+  end
+
+  ##
+  # Creates the JSON index.
+
+  def generate top_levels
+    debug_msg "Generating JSON index"
+
+    reset top_levels.sort, RDoc::TopLevel.all_classes_and_modules.sort
+
+    index_classes
+    index_methods
+    index_pages
+
+    debug_msg "  writing search index to %s" % SEARCH_INDEX_FILE
+    data = { :index => @index }
+
+    return if @options.dry_run
+
+    out_dir = @base_dir + @options.op_dir
+    index_file = out_dir + SEARCH_INDEX_FILE
+
+    FileUtils.mkdir_p index_file.dirname, :verbose => $DEBUG_RDOC
+
+    index_file.open 'w', 0644 do |io|
+      io.set_encoding Encoding::UTF_8 if Object.const_defined? :Encoding
+      io.write 'var search_data = '
+
+      JSON.dump data, io, 0
+    end
+
+    Dir.chdir @template_dir do
+      Dir['**/*.js'].each do |source|
+        dest = File.join out_dir, source
+
+        FileUtils.install source, dest, :mode => 0644, :verbose => $DEBUG_RDOC
+      end
+    end
+  end
+
+  ##
+  # Adds classes and modules to the index
+
+  def index_classes
+    debug_msg "  generating class search index"
+
+    documented = @classes.uniq.select do |klass|
+      klass.document_self_or_methods
+    end
+
+    documented.each do |klass|
+      debug_msg "    #{klass.full_name}"
+      record = klass.search_record
+      @index[:searchIndex]     << search_string(record.shift)
+      @index[:longSearchIndex] << search_string(record.shift)
+      @index[:info]            << record
+    end
+  end
+
+  ##
+  # Adds methods to the index
+
+  def index_methods
+    debug_msg "  generating method search index"
+
+    list = @classes.uniq.map do |klass|
+      klass.method_list
+    end.flatten.sort_by do |method|
+      [method.name, method.parent.full_name]
+    end
+
+    list.each do |method|
+      debug_msg "    #{method.full_name}"
+      record = method.search_record
+      @index[:searchIndex]     << "#{search_string record.shift}()"
+      @index[:longSearchIndex] << "#{search_string record.shift}()"
+      @index[:info]            << record
+    end
+  end
+
+  ##
+  # Adds pages to the index
+
+  def index_pages
+    debug_msg "  generating pages search index"
+
+    pages = @files.select do |file|
+      file.text?
+    end
+
+    pages.each do |page|
+      debug_msg "    #{page.page_name}"
+      record = page.search_record
+      @index[:searchIndex]     << search_string(record.shift)
+      @index[:longSearchIndex] << ''
+      record.shift
+      @index[:info]            << record
+    end
+  end
+
+  ##
+  # The directory classes are written to
+
+  def class_dir
+    @parent_generator.class_dir
+  end
+
+  ##
+  # The directory files are written to
+
+  def file_dir
+    @parent_generator.file_dir
+  end
+
+  def reset files, classes # :nodoc:
+    @files   = files
+    @classes = classes
+
+    @index = {
+      :searchIndex => [],
+      :longSearchIndex => [],
+      :info => []
+    }
+  end
+
+  ##
+  # Removes whitespace and downcases +string+
+
+  def search_string string
+    string.downcase.gsub(/\s/, '')
+  end
+
+end
+

data/lib/rdoc/generator/markup.rb

@@ -1,14 +1,9 @@
-# This file is loaded by generators.  It allows RDoc's CodeObject tree to
-# avoid loading generator code to increase startup time (for ri).
-
-require 'rdoc/text'
-require 'rdoc/code_objects'
-require 'rdoc/generator'
-require 'rdoc/markup/to_html_crossref'
-require 'rdoc/ruby_token'
 
 ##
 # Handle common RDoc::Markup tasks for various CodeObjects
+#
+# This module is loaded by generators.  It allows RDoc's CodeObject tree to
+# avoid loading generator code to improve startup time for +ri+.
 
 module RDoc::Generator::Markup
 
@@ -45,6 +40,8 @@ module RDoc::Generator::Markup
 
     @formatter = RDoc::Markup::ToHtmlCrossref.new(this.path, this, show_hash,
                                                   hyperlink_all)
+    @formatter.code_object = self
+    @formatter
   end
 
   ##
@@ -62,10 +59,14 @@ module RDoc::Generator::Markup
 
 end
 
-class RDoc::AnyMethod
+class RDoc::CodeObject
 
   include RDoc::Generator::Markup
 
+end
+
+class RDoc::AnyMethod
+
   @add_line_numbers = false
 
   class << self
@@ -111,32 +112,7 @@ class RDoc::AnyMethod
   def markup_code
     return '' unless @token_stream
 
-    src = ""
-
-    @token_stream.each do |t|
-      next unless t
-
-      style = case t
-              when RDoc::RubyToken::TkCONSTANT then 'ruby-constant'
-              when RDoc::RubyToken::TkKW       then 'ruby-keyword'
-              when RDoc::RubyToken::TkIVAR     then 'ruby-ivar'
-              when RDoc::RubyToken::TkOp       then 'ruby-operator'
-              when RDoc::RubyToken::TkId       then 'ruby-identifier'
-              when RDoc::RubyToken::TkNode     then 'ruby-node'
-              when RDoc::RubyToken::TkCOMMENT  then 'ruby-comment'
-              when RDoc::RubyToken::TkREGEXP   then 'ruby-regexp'
-              when RDoc::RubyToken::TkSTRING   then 'ruby-string'
-              when RDoc::RubyToken::TkVal      then 'ruby-value'
-              end
-
-      text = CGI.escapeHTML t.text
-
-      if style then
-        src << "<span class=\"#{style}\">#{text}</span>"
-      else
-        src << text
-      end
-    end
+    src = RDoc::TokenStream.to_html @token_stream
 
     # dedent the source
     indent = src.length
@@ -158,27 +134,14 @@ class RDoc::AnyMethod
 
 end
 
-class RDoc::Attr
-
-  include RDoc::Generator::Markup
-
-end
-
-class RDoc::Alias
+class RDoc::ClassModule
 
-  include RDoc::Generator::Markup
-
-end
-
-class RDoc::Constant
-
-  include RDoc::Generator::Markup
-
-end
-
-class RDoc::Context
+  ##
+  # Handy wrapper for marking up this class or module's comment
 
-  include RDoc::Generator::Markup
+  def description
+    markup @comment_location
+  end
 
 end
 

data/lib/rdoc/generator/ri.rb

@@ -1,6 +1,3 @@
-require 'rdoc/generator'
-require 'rdoc/ri'
-
 ##
 # Generates ri data files
 

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

@@ -0,0 +1,5 @@
+<footer id="validator-badges">
+  <p><a href="http://validator.w3.org/check/referer">[Validate]</a>
+  <p>Generated by <a href="https://github.com/rdoc/rdoc">RDoc</a> <%= RDoc::VERSION %>.
+  <p>Generated with the <a href="http://deveiate.org/projects/Darkfish-Rdoc/">Darkfish Rdoc Generator</a> <%= RDoc::Generator::Darkfish::VERSION %>.
+</footer>

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

@@ -0,0 +1,16 @@
+<meta content="text/html; charset=<%= @options.charset %>" http-equiv="Content-Type">
+
+<title><%= h @title %></title>
+
+<link type="text/css" media="screen" href="<%= rel_prefix %>/rdoc.css" rel="stylesheet">
+
+<script type="text/javascript">
+  var rdoc_rel_prefix = "<%= rel_prefix %>/";
+</script>
+
+<script type="text/javascript" charset="utf-8" src="<%= rel_prefix %>/js/jquery.js"></script>
+<script type="text/javascript" charset="utf-8" src="<%= rel_prefix %>/js/navigation.js"></script>
+<script type="text/javascript" charset="utf-8" src="<%= rel_prefix %>/js/search_index.js"></script>
+<script type="text/javascript" charset="utf-8" src="<%= rel_prefix %>/js/search.js"></script>
+<script type="text/javascript" charset="utf-8" src="<%= rel_prefix %>/js/searcher.js"></script>
+<script type="text/javascript" charset="utf-8" src="<%= rel_prefix %>/js/darkfish.js"></script>

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

@@ -0,0 +1,18 @@
+<% if !svninfo.empty? then %>
+<nav id="file-svninfo-section" class="section">
+  <h3 class="section-header">VCS Info</h3>
+  <div class="section-body">
+    <dl class="svninfo">
+      <dt>Rev
+      <dd><%= svninfo[:rev] %>
+
+      <dt>Last Checked In
+      <dd><%= svninfo[:commitdate].strftime('%Y-%m-%d %H:%M:%S') %>
+        (<%= svninfo[:commitdelta] %> ago)
+
+      <dt>Checked in by
+      <dd><%= svninfo[:committer] %>
+    </dl>
+  </div>
+</nav>
+<% end %>

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

@@ -0,0 +1,9 @@
+<nav id="classindex-section" class="section project-section">
+  <h3 class="section-header">Class and Module Index</h3>
+
+  <ul class="link-list">
+  <% @modsort.each do |index_klass| %>
+    <li><a href="<%= rel_prefix %>/<%= index_klass.path %>"><%= index_klass.full_name %></a>
+  <% end %>
+  </ul>
+</nav>

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

@@ -0,0 +1,8 @@
+<nav id="file-list-section" class="section">
+  <h3 class="section-header">Defined In</h3>
+  <ul>
+<% klass.in_files.each do |tl| %>
+    <li><%= h tl.absolute_name %>
+<% end %>
+  </ul>
+</nav>

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

@@ -0,0 +1,16 @@
+<% unless klass.includes.empty? then %>
+<!-- Included Modules -->
+<nav 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 then %>
+    <li><a class="include" href="<%= klass.aref_to inc.module.path %>"><%= inc.module.full_name %></a>
+  <% else %>
+    <li><span class="include"><%= inc.name %></span>
+  <% end %>
+  <% end %>
+  </ul>
+</nav>
+<% end %>

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

@@ -0,0 +1,12 @@
+<% unless klass.method_list.empty? then %>
+<!-- Method Quickref -->
+<nav 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 ? '::' : '#' %><%= h meth.name %></a>
+    <% end %>
+  </ul>
+</nav>
+<% end %>