rdoc 3.9.5 → 3.10.pre.1

data/lib/rdoc/constant.rb

@@ -1,5 +1,3 @@
-require 'rdoc/code_object'
-
 ##
 # A constant
 

data/lib/rdoc/context.rb

@@ -1,4 +1,4 @@
-require 'rdoc/code_object'
+require 'cgi'
 
 ##
 # A Context is something that can hold modules, classes, methods, attributes,
@@ -14,6 +14,12 @@ class RDoc::Context < RDoc::CodeObject
 
   TYPES = %w[class instance]
 
+  ##
+  # If a context has these titles it will be sorted in this order.
+
+  TOMDOC_TITLES = [nil, 'Public', 'Internal', 'Deprecated'] # :nodoc:
+  TOMDOC_TITLES_SORT = TOMDOC_TITLES.sort_by { |title| title.to_s } # :nodoc:
+
   ##
   # Class/module aliases
 
@@ -92,118 +98,6 @@ class RDoc::Context < RDoc::CodeObject
 
   attr_reader :constants_hash
 
-  ##
-  # A section of documentation like:
-  #
-  #   # :section: The title
-  #   # The body
-  #
-  # Sections can be referenced multiple times and will be collapsed into a
-  # single section.
-
-  class Section
-
-    include RDoc::Text
-
-    ##
-    # Section comment
-
-    attr_reader :comment
-
-    ##
-    # Context this Section lives in
-
-    attr_reader :parent
-
-    ##
-    # Section title
-
-    attr_reader :title
-
-    @@sequence = "SEC00000"
-
-    ##
-    # Creates a new section with +title+ and +comment+
-
-    def initialize parent, title, comment
-      @parent = parent
-      @title = title ? title.strip : title
-
-      @@sequence.succ!
-      @sequence = @@sequence.dup
-
-      @comment = extract_comment comment
-    end
-
-    ##
-    # Sections are equal when they have the same #title
-
-    def == other
-      self.class === other and @title == other.title
-    end
-
-    ##
-    # Anchor reference for linking to this section
-
-    def aref
-      title = @title || '[untitled]'
-
-      CGI.escape(title).gsub('%', '-').sub(/^-/, '')
-    end
-
-    ##
-    # Appends +comment+ to the current comment separated by a rule.
-
-    def comment= comment
-      comment = extract_comment comment
-
-      return if comment.empty?
-
-      if @comment then
-        @comment += "\n# ---\n#{comment}"
-      else
-        @comment = comment
-      end
-    end
-
-    ##
-    # Extracts the comment for this section from the original comment block.
-    # If the first line contains :section:, strip it and use the rest.
-    # Otherwise remove lines up to the line containing :section:, and look
-    # for those lines again at the end and remove them. This lets us write
-    #
-    #   # :section: The title
-    #   # The body
-
-    def extract_comment comment
-      if comment =~ /^#[ \t]*:section:.*\n/ then
-        start = $`
-        rest = $'
-
-        if start.empty? then
-          rest
-        else
-          rest.sub(/#{start.chomp}\Z/, '')
-        end
-      else
-        comment
-      end
-    end
-
-    def inspect # :nodoc:
-      "#<%s:0x%x %p>" % [self.class, object_id, title]
-    end
-
-    ##
-    # Section sequence number (deprecated)
-
-    def sequence
-      warn "RDoc::Context::Section#sequence is deprecated, use #aref"
-      @sequence
-    end
-
-  end
-
   ##
   # Creates an unnamed empty context with public current visibility
 
@@ -602,9 +496,9 @@ class RDoc::Context < RDoc::CodeObject
   #
   # See also RDoc::Context::Section
 
-  def add_section title, comment
+  def add_section title, comment = nil
     if section = @sections[title] then
-      section.comment = comment
+      section.comment = comment if comment
     else
       section = Section.new self, title, comment
       @sections[title] = section
@@ -773,13 +667,15 @@ class RDoc::Context < RDoc::CodeObject
   # NOTE: Do not edit collections yielded by this method
 
   def each_section # :yields: section, constants, attributes
+    return enum_for __method__ unless block_given?
+
     constants  = @constants.group_by  do |constant|  constant.section end
     constants.default = []
 
     attributes = @attributes.group_by do |attribute| attribute.section end
     attributes.default = []
 
-    @sections.sort_by { |title, _| title.to_s }.each do |_, section|
+    sort_sections.each do |section|
       yield section, constants[section].sort, attributes[section].sort
     end
   end
@@ -1098,15 +994,14 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Only called when min_visibility == :public or :private
 
-  def remove_invisible_in(array, min_visibility) # :nodoc:
-    if min_visibility == :public
+  def remove_invisible_in array, min_visibility # :nodoc:
+    if min_visibility == :public then
       array.reject! { |e|
         e.visibility != :public and not e.force_documentation
       }
     else
       array.reject! { |e|
-        e.visibility == :private and
-          not e.force_documentation
+        e.visibility == :private and not e.force_documentation
       }
     end
   end
@@ -1155,6 +1050,26 @@ class RDoc::Context < RDoc::CodeObject
     end
   end
 
+  ##
+  # Sorts sections alphabetically (default) or in TomDoc fasion (none, Public,
+  # Internal, Deprecated)
+
+  def sort_sections
+    titles = @sections.map { |title, _| title }
+
+    if titles.length > 1 and
+       TOMDOC_TITLES_SORT ==
+         (titles | TOMDOC_TITLES).sort_by { |title| title.to_s } then
+      @sections.values_at(*TOMDOC_TITLES).compact
+    else
+      @sections.sort_by { |title, _|
+        title.to_s
+      }.map { |_, section|
+        section
+      }
+    end
+  end
+
   def to_s # :nodoc:
     "#{self.class.name} #{self.full_name}"
   end
@@ -1187,5 +1102,7 @@ class RDoc::Context < RDoc::CodeObject
     klass
   end
 
+  autoload :Section, 'rdoc/context/section'
+
 end
 

data/lib/rdoc/context/section.rb

@@ -0,0 +1,114 @@
+##
+# A section of documentation like:
+#
+#   # :section: The title
+#   # The body
+#
+# Sections can be referenced multiple times and will be collapsed into a
+# single section.
+
+class RDoc::Context::Section
+
+  include RDoc::Text
+
+  ##
+  # Section comment
+
+  attr_reader :comment
+
+  ##
+  # Context this Section lives in
+
+  attr_reader :parent
+
+  ##
+  # Section title
+
+  attr_reader :title
+
+  @@sequence = "SEC00000"
+
+  ##
+  # Creates a new section with +title+ and +comment+
+
+  def initialize parent, title, comment
+    @parent = parent
+    @title = title ? title.strip : title
+
+    @@sequence.succ!
+    @sequence = @@sequence.dup
+
+    @comment = nil
+    @comment = extract_comment comment if comment
+  end
+
+  ##
+  # Sections are equal when they have the same #title
+
+  def == other
+    self.class === other and @title == other.title
+  end
+
+  ##
+  # Anchor reference for linking to this section
+
+  def aref
+    title = @title || '[untitled]'
+
+    CGI.escape(title).gsub('%', '-').sub(/^-/, '')
+  end
+
+  ##
+  # Appends +comment+ to the current comment separated by a rule.
+
+  def comment= comment
+    comment = extract_comment comment
+
+    return if comment.empty?
+
+    if @comment then
+      # HACK should section comments get joined?
+      @comment.text += "\n# ---\n#{comment.text}"
+    else
+      @comment = comment
+    end
+  end
+
+  ##
+  # Extracts the comment for this section from the original comment block.
+  # If the first line contains :section:, strip it and use the rest.
+  # Otherwise remove lines up to the line containing :section:, and look
+  # for those lines again at the end and remove them. This lets us write
+  #
+  #   # :section: The title
+  #   # The body
+
+  def extract_comment comment
+    if comment.text =~ /^#[ \t]*:section:.*\n/ then
+      start = $`
+      rest = $'
+
+      comment.text = if start.empty? then
+                       rest
+                     else
+                       rest.sub(/#{start.chomp}\Z/, '')
+                     end
+    end
+
+    comment
+  end
+
+  def inspect # :nodoc:
+    "#<%s:0x%x %p>" % [self.class, object_id, title]
+  end
+
+  ##
+  # Section sequence number (deprecated)
+
+  def sequence
+    warn "RDoc::Context::Section#sequence is deprecated, use #aref"
+    @sequence
+  end
+
+end
+

data/lib/rdoc/cross_reference.rb

@@ -18,7 +18,7 @@ class RDoc::CrossReference
   #
   # See CLASS_REGEXP_STR
 
-  METHOD_REGEXP_STR = '([a-z]\w*[!?=]?)(?:\([\w.+*/=<>-]*\))?'
+  METHOD_REGEXP_STR = '([a-z]\w*[!?=]?|%)(?:\([\w.+*/=<>-]*\))?'
 
   ##
   # Regular expressions matching text that should potentially have
@@ -51,19 +51,22 @@ class RDoc::CrossReference
                       # after the cross-reference is a space, sentence
                       # punctuation, tag start character, or attribute
                       # marker.
-                      | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;<\000]|\z)
+                      | #{CLASS_REGEXP_STR}(?=[@\s).?!,;<\000]|\z)
 
                       # Things that look like filenames
                       # The key thing is that there must be at least
                       # one special character (period, slash, or
                       # underscore).
-                      | (?:\.\.\/)*[-\/\w]+[_\/\.][-\w\/\.]+
+                      | (?:\.\.\/)*[-\/\w]+[_\/.][-\w\/.]+
 
                       # Things that have markup suppressed
                       # Don't process things like '\<' in \<tt>, though.
                       # TODO: including < is a hack, not very satisfying.
                       | \\[^\s<]
-                      )/x
+                      )
+
+                      # labels for headings
+                      (?:@[\w+%-]+)?/x
 
   ##
   # Version of CROSSREF_REGEXP used when <tt>--hyperlink-all</tt> is specified.
@@ -76,14 +79,20 @@ class RDoc::CrossReference
                       | \\?#{METHOD_REGEXP_STR}
 
                       # A::B::C
-                      | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;<\000]|\z)
+                      | #{CLASS_REGEXP_STR}(?=[@\s).?!,;<\000]|\z)
 
                       # Things that look like filenames
-                      | (?:\.\.\/)*[-\/\w]+[_\/\.][-\w\/\.]+
+                      | (?:\.\.\/)*[-\/\w]+[_\/.][-\w\/.]+
 
                       # Things that have markup suppressed
                       | \\[^\s<]
-                      )/x
+                      )
+
+                      # labels for headings
+                      (?:@[\w+%-]+)?/x
+
+  ##
+  # Hash of references that have been looked-up to their replacements
 
   attr_accessor :seen
 

data/lib/rdoc/encoding.rb

@@ -1,7 +1,5 @@
 # coding: US-ASCII
 
-require 'rdoc'
-
 ##
 # This class is a wrapper around File IO and Encoding that helps RDoc load
 # files and convert them to the correct encoding.

data/lib/rdoc/gauntlet.rb

@@ -1,4 +1,4 @@
-require 'rdoc/rdoc'
+require 'rdoc'
 require 'gauntlet'
 require 'fileutils'
 

data/lib/rdoc/generator.rb

@@ -1,5 +1,3 @@
-require 'rdoc'
-
 ##
 # RDoc uses generators to turn parsed source code in the form of an
 # RDoc::CodeObject tree into some form of output.  RDoc comes with the HTML
@@ -36,5 +34,12 @@ require 'rdoc'
 # to create your desired output format.
 
 module RDoc::Generator
+
+  autoload :Markup,   'rdoc/generator/markup'
+
+  autoload :Darkfish,  'rdoc/generator/darkfish'
+  autoload :JsonIndex, 'rdoc/generator/json_index'
+  autoload :RI,        'rdoc/generator/ri'
+
 end
 

data/lib/rdoc/generator/darkfish.rb

@@ -1,9 +1,8 @@
 # -*- mode: ruby; ruby-indent-level: 2; tab-width: 2 -*-
 
-require 'pathname'
+require 'erb'
 require 'fileutils'
-require 'rdoc/erbio'
-
+require 'pathname'
 require 'rdoc/generator/markup'
 
 ##
@@ -46,6 +45,11 @@ require 'rdoc/generator/markup'
 # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# == Attributions
+#
+# Darkfish uses the {Silk Icons}[http://www.famfamfam.com/lab/icons/silk/] set
+# by Mark James.
 
 class RDoc::Generator::Darkfish
 
@@ -53,6 +57,7 @@ class RDoc::Generator::Darkfish
 
   include ERB::Util
 
+  ##
   # Path to this file's parent directory. Used to find templates and other
   # resources.
 
@@ -61,13 +66,19 @@ class RDoc::Generator::Darkfish
   ##
   # Release Version
 
-  VERSION = '2'
+  VERSION = '3'
 
   ##
   # Description of this generator
 
   DESCRIPTION = 'HTML generator, written by Michael Granger'
 
+  ##
+  # The path to generate files into, combined with <tt>--op</tt> from the
+  # options for a full path.
+
+  attr_reader :base_dir
+
   ##
   # Initialize a few instance variables before we start
 
@@ -80,7 +91,9 @@ class RDoc::Generator::Darkfish
     @files      = nil
     @classes    = nil
 
-    @basedir = Pathname.pwd.expand_path
+    @base_dir = Pathname.pwd.expand_path
+
+    @json_index = RDoc::Generator::JsonIndex.new self, options
   end
 
   ##
@@ -149,7 +162,7 @@ class RDoc::Generator::Darkfish
   # objects containing the extracted information.
 
   def generate top_levels
-    @outputdir = Pathname.new(@options.op_dir).expand_path(@basedir)
+    @outputdir = Pathname.new(@options.op_dir).expand_path(@base_dir)
 
     @files = top_levels.sort
     @classes = RDoc::TopLevel.all_classes_and_modules.sort
@@ -161,6 +174,8 @@ class RDoc::Generator::Darkfish
     generate_index
     generate_class_files
     generate_file_files
+    generate_table_of_contents
+    @json_index.generate top_levels
 
   rescue => e
     debug_msg "%s: %s\n  %s" % [
@@ -205,7 +220,10 @@ class RDoc::Generator::Darkfish
 
     debug_msg "Rendering the index page..."
 
-    out_file = @basedir + @options.op_dir + 'index.html'
+    out_file = @base_dir + @options.op_dir + 'index.html'
+    # suppress 1.9.3 warning
+    rel_prefix = rel_prefix = @outputdir.relative_path_from(out_file.dirname)
+    @title = @options.title
 
     render_template template_file, out_file do |io| binding end
   rescue => e
@@ -217,10 +235,12 @@ class RDoc::Generator::Darkfish
   end
 
   ##
-  # Generate a documentation file for each class
+  # Generate a documentation file for each class and module
 
   def generate_class_files
-    template_file = @template_dir + 'classpage.rhtml'
+    template_file = @template_dir + 'class.rhtml'
+    template_file = @template_dir + 'classpage.rhtml' unless
+      template_file.exist?
     return unless template_file.exist?
     debug_msg "Generating class documentation in #{@outputdir}"
 
@@ -233,6 +253,7 @@ class RDoc::Generator::Darkfish
       # suppress 1.9.3 warning
       rel_prefix = rel_prefix = @outputdir.relative_path_from(out_file.dirname)
       svninfo    = svninfo    = self.get_svninfo(klass)
+      @title = "#{klass.type.capitalize}: #{klass.full_name}"
 
       debug_msg "  rendering #{out_file}"
       render_template template_file, out_file do |io| binding end
@@ -249,8 +270,13 @@ class RDoc::Generator::Darkfish
   # Generate a documentation file for each file
 
   def generate_file_files
-    template_file = @template_dir + 'filepage.rhtml'
-    return unless template_file.exist?
+    page_file     = @template_dir + 'page.rhtml'
+    fileinfo_file = @template_dir + 'fileinfo.rhtml'
+    template_file = @template_dir + 'filepage.rhtml' unless
+      page_file.exist? or fileinfo_file.exist?
+
+    return unless
+      page_file.exist? or fileinfo_file.exist? or template_file.exist?
     debug_msg "Generating file documentation in #{@outputdir}"
 
     out_file = nil
@@ -259,9 +285,20 @@ class RDoc::Generator::Darkfish
       out_file     = @outputdir + file.path
       debug_msg "  working on %s (%s)" % [file.full_name, out_file]
       # suppress 1.9.3 warning
-      rel_prefix = rel_prefix  = @outputdir.relative_path_from(out_file.dirname)
+      rel_prefix = rel_prefix = @outputdir.relative_path_from(out_file.dirname)
+
+      unless template_file then
+        if file.text? then
+          next unless page_file.exist?
+          template_file = page_file
+          @title = file.page_name
+        else
+          next unless fileinfo_file.exist?
+          template_file = fileinfo_file
+          @title = "File: #{file.base_name} [#{@options.title}]"
+        end
+      end
 
-      debug_msg "  rendering #{out_file}"
       render_template template_file, out_file do |io| binding end
     end
   rescue => e
@@ -272,6 +309,29 @@ class RDoc::Generator::Darkfish
     raise error
   end
 
+  ##
+  # Generate an index page which lists all the classes which are documented.
+
+  def generate_table_of_contents
+    template_file = @template_dir + 'table_of_contents.rhtml'
+    return unless template_file.exist?
+
+    debug_msg "Rendering the Table of Contents..."
+
+    out_file = @base_dir + @options.op_dir + 'table_of_contents.html'
+    # suppress 1.9.3 warning
+    rel_prefix = rel_prefix = @outputdir.relative_path_from(out_file.dirname)
+    @title = "Table of Contents"
+
+    render_template template_file, out_file do |io| binding end
+  rescue => e
+    error = RDoc::Error.new \
+      "error generating table_of_contents.html: #{e.message} (#{e.class})"
+    error.set_backtrace e.backtrace
+
+    raise error
+  end
+
   ##
   # Return a string describing the amount of time in the given number of
   # seconds in terms a human can understand easily.
@@ -324,6 +384,46 @@ class RDoc::Generator::Darkfish
     }
   end
 
+  ##
+  # Creates a template from its components and the +body_file+.
+  #
+  # For backwards compatibility, if +body_file+ contains "<html" the body is
+  # used directly.
+
+  def assemble_template body_file
+    body = body_file.read
+    return body if body =~ /<html/
+
+    head_file = @template_dir + '_head.rhtml'
+    footer_file = @template_dir + '_footer.rhtml'
+
+    <<-TEMPLATE
+<!DOCTYPE html>
+
+<html>
+<head>
+#{head_file.read}
+
+#{body}
+
+#{footer_file.read}
+    TEMPLATE
+  end
+
+  ##
+  # Renders the ERb contained in +file_name+ relative to the template
+  # directory and returns the result based on the current context.
+
+  def render file_name
+    template_file = @template_dir + file_name
+
+    template = template_for template_file, false, ERB
+
+    template.filename = template_file.to_s
+
+    template.result @context
+  end
+
   ##
   # Load and render the erb template in the given +template_file+ and write
   # it out to +out_file+.
@@ -342,14 +442,14 @@ class RDoc::Generator::Darkfish
       out_file.open 'w', 0644 do |io|
         io.set_encoding @options.encoding if Object.const_defined? :Encoding
 
-        context = yield io
+        @context = yield io
 
-        template_result template, context, template_file
+        template_result template, @context, template_file
       end
     else
-      context = yield nil
+      @context = yield nil
 
-      output = template_result template, context, template_file
+      output = template_result template, @context, template_file
 
       debug_msg "  would have written %d characters to %s" % [
         output.length, out_file.expand_path
@@ -374,14 +474,20 @@ class RDoc::Generator::Darkfish
   ##
   # Retrieves a cache template for +file+, if present, or fills the cache.
 
-  def template_for file
+  def template_for file, page = true, klass = nil
     template = @template_cache[file]
 
     return template if template
 
-    klass = @options.dry_run ? ERB : RDoc::ERBIO
+    klass = @options.dry_run ? ERB : RDoc::ERBIO unless klass
+
+    template = if page then
+                 assemble_template file
+               else
+                 file.read
+               end
 
-    template = klass.new file.read, nil, '<>'
+    template = klass.new template, nil, '<>'
     @template_cache[file] = template
     template
   end