rdoc 4.0.0.preview2 → 4.0.0.preview2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 !binary "U0hBMQ==":
-  metadata.gz: bd558c2cff419547ec57eda5fe512659e1dd04b4
-  data.tar.gz: 1981e42e56784ea75c8bd9b9428e3da5c3ec695b
+  metadata.gz: be465a9f7229b4fa46271d90e7102066498c0b4d
+  data.tar.gz: f5297b952027d39046fcea6d3c4ead0fe569f40c
 !binary "U0hBNTEy":
-  metadata.gz: c3cebbb886df27b7ffb2288b958247f84e7b6a286dc0438544012d51d8402e804f84099ea421277c40b26b82f70c5c83d47a72bfe395c183273f885355925f98
-  data.tar.gz: be6380482a950fd82393784de7df78027ea3ea70f83d2e863041a9400fd56e84ace8f5a240a1247b7e4c36745b004ea810893e332b54b9aa43d0762691d26314
+  metadata.gz: a4bbe645b202903651d0b3fa0d79bd331c2b7becd9d7feed0d24d215821a6625c27f6db475d3c495ddc3652651afe00c75d7c3a7dadad7c97948c7934c7d675a
+  data.tar.gz: 297ea3814b07df111090a99500b10f9f9a4e99448e9626b1f304d659e4b5d1fdf03a8f60562ecb25448e74e661efeae87d982f67a84f857c06db8ca9319cc527

data/.autotest

@@ -15,7 +15,10 @@ Autotest.add_hook :initialize do |at|
     f = s.sub(/^test#{sep}/, '').sub(/\.rb$/, '').split(sep)
     f = f.map { |path| path.split(/_|(\d+)/).map { |seg| seg.capitalize }.join }
     f = f.map { |path| path =~ /^Test/ ? path : "Test#{path}"  }
-    f.join('::').gsub('Rdoc', 'RDoc').gsub('Ri', 'RI')
+    f.join('::').
+      gsub('Rdoc', 'RDoc').
+      gsub('Ri', 'RI').
+      gsub('Changelog', 'ChangeLog')
   end
 end
 

data/History.rdoc

@@ -1,4 +1,4 @@
-=== 4.0.0.preview2
+=== 4.0.0.preview2.1 / 2012-12-14
 
 As a preview release, please file bugs for any problems you have with rdoc at
 https://github.com/rdoc/rdoc/issues
@@ -10,6 +10,29 @@ Notable feature additions are markdown support and an WEBrick servlet that can
 serve HTML from an ri store.  (This means that RubyGems 2.0+ no longer needs
 to build HTML documentation when installing gems.)
 
+* Minor enhancements
+  * Added --page-dir option to give pretty names for a FAQ, guides, or other
+    documentation you write that is not stored in the project root.  For
+    example, with the following layout:
+
+      README.txt
+      guides/syntax.txt
+      guides/conversion.txt
+
+    Running `rdoc --page-dir guides` will make the files in "guides" appear to
+    be at the top level of the project.  This means they will appear to exist
+    at the top level in HTML output and you can access them with
+    `ri your_gem:syntax` and `ri your_gem:conversion`.
+
+* Bug fixes
+  * Fully qualified names for constants declared from the top level are now
+    attached to their class or module properly.
+  * Fixed table of contents display in HTML output for classes and modules.
+  * Incremental ri builds of C files now work.  C variable names from previous
+    runs are now saved between runs.
+
+=== 4.0.0.preview2 / 2012-12-01
+
 * Breaking changes
   * The default output encoding for RDoc is now UTF-8.  Previously RDoc used
     the default external encoding which was determined from your locale.
@@ -79,6 +102,8 @@ to build HTML documentation when installing gems.)
 
 * Minor enhancements
   * Added --root for building documentation from outside the source dir.
+  * Added a ChangeLog parser.  It automatically parses files that begin
+    with 'ChangeLog'
   * Added a table of contents to the sidebar.
   * RDoc markup format merges adjacent labels in a label or note list into a
     single definition list item for output.

data/Manifest.txt

@@ -141,6 +141,7 @@ lib/rdoc/normal_module.rb
 lib/rdoc/options.rb
 lib/rdoc/parser.rb
 lib/rdoc/parser/c.rb
+lib/rdoc/parser/changelog.rb
 lib/rdoc/parser/markdown.rb
 lib/rdoc/parser/rd.rb
 lib/rdoc/parser/ruby.rb
@@ -256,6 +257,7 @@ test/test_rdoc_normal_module.rb
 test/test_rdoc_options.rb
 test/test_rdoc_parser.rb
 test/test_rdoc_parser_c.rb
+test/test_rdoc_parser_changelog.rb
 test/test_rdoc_parser_markdown.rb
 test/test_rdoc_parser_rd.rb
 test/test_rdoc_parser_ruby.rb

data/Rakefile

@@ -103,7 +103,7 @@ task "#{path}.gem" => package_parser_files
 # RUBINIUS_PATH.
 
 diff_options = "-urpN --exclude '*svn*' --exclude '*swp' --exclude '*rbc'"
-rsync_options = "-avP --exclude '*svn*' --exclude '*swp' --exclude '*rbc' --exclude '*.rej' --exclude '*.orig'"
+rsync_options = "-avP --exclude '*svn*' --exclude '*swp' --exclude '*rbc' --exclude '*.rej' --exclude '*.orig' --exclude '*.kpeg' --exclude '*.ry' --exclude 'literals_1_8.rb' --exclude 'gauntlet_rdoc.rb'"
 
 rubinius_dir = ENV['RUBINIUS_PATH'] || '../../../git/git.rubini.us/code'
 ruby_dir = ENV['RUBY_PATH'] || '../../svn/ruby/trunk'

data/lib/rdoc.rb

@@ -64,7 +64,7 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '4.0.0.preview2'
+  VERSION = '4.0.0.preview2.1'
 
   ##
   # Method visibilities

data/lib/rdoc/class_module.rb

@@ -31,7 +31,7 @@ class RDoc::ClassModule < RDoc::Context
   ##
   # Comment and the location it came from.  Use #add_comment to add comments
 
-  attr_reader :comment_location
+  attr_accessor :comment_location
 
   attr_accessor :diagram # :nodoc:
 
@@ -134,6 +134,9 @@ class RDoc::ClassModule < RDoc::Context
               else
                 normalize_comment comment
               end
+
+    @comment_location.delete_if { |(_, l)| l == location }
+
     @comment_location << [comment, location]
 
     self.comment = original
@@ -184,7 +187,7 @@ class RDoc::ClassModule < RDoc::Context
   # Appends +comment+ to the current comment, but separated by a rule.  Works
   # more like <tt>+=</tt>.
 
-  def comment= comment
+  def comment= comment # :nodoc:
     comment = case comment
               when RDoc::Comment then
                 comment.normalize
@@ -216,6 +219,14 @@ class RDoc::ClassModule < RDoc::Context
     document_self || method_list.any?{ |m| m.document_self }
   end
 
+  ##
+  # Does this class or module have a comment with content or is
+  # #received_nodoc true?
+
+  def documented?
+    super or !@comment_location.empty?
+  end
+
   ##
   # Iterates the ancestors of this class or module for which an
   # RDoc::ClassModule exists.

data/lib/rdoc/context.rb

@@ -447,11 +447,13 @@ class RDoc::Context < RDoc::CodeObject
     known = @methods_hash[key]
 
     if known then
-      known.comment = method.comment if known.comment.empty?
-      previously = ", previously in #{known.file}" unless
-        method.file == known.file
-      @store.rdoc.options.warn \
-        "Duplicate method #{known.full_name} in #{method.file}#{previously}"
+      if @store then # otherwise we are loading
+        known.comment = method.comment if known.comment.empty?
+        previously = ", previously in #{known.file}" unless
+          method.file == known.file
+        @store.rdoc.options.warn \
+          "Duplicate method #{known.full_name} in #{method.file}#{previously}"
+      end
     else
       @methods_hash[key] = method
       method.visibility = @visibility

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

@@ -1,4 +1,10 @@
-<% table = current.parse(current.comment).table_of_contents
+<% comment = if current.respond_to? :comment_location then
+               current.comment_location
+             else
+               current.comment
+             end
+   table = current.parse(comment).table_of_contents
+
    if table.length > 1 then %>
 <div id="table-of-contents">
   <nav class="section">

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

@@ -30,7 +30,7 @@
   <li class="<%= klass.type %>">
     <a href="<%= klass.path %>"><%= klass.full_name %></a>
 <% table = []
-   table.concat klass.parse(klass.comment).table_of_contents
+   table.concat klass.parse(klass.comment_location).table_of_contents
    table.concat klass.section_contents
 
    unless table.empty? then %>

data/lib/rdoc/markdown/entities.rb

@@ -1,3 +1,6 @@
+##
+# HTML entity name map for RDoc::Markdown
+
 RDoc::Markdown::HTML_ENTITIES = {
   "AElig" => [0x000C6],
   "AMP" => [0x00026],

data/lib/rdoc/markup/document.rb

@@ -11,6 +11,12 @@ class RDoc::Markup::Document
 
   attr_reader :file
 
+  ##
+  # If a heading is below the given level it will be omitted from the
+  # table_of_contents
+
+  attr_accessor :omit_headings_below
+
   ##
   # The parts of the Document
 
@@ -24,6 +30,7 @@ class RDoc::Markup::Document
     @parts.concat parts
 
     @file = nil
+    @omit_headings_from_table_of_contents_below = nil
   end
 
   ##
@@ -57,14 +64,7 @@ class RDoc::Markup::Document
   def accept visitor
     visitor.start_accepting
 
-    @parts.each do |item|
-      case item
-      when RDoc::Markup::Document then # HACK
-        visitor.accept_document item
-      else
-        item.accept visitor
-      end
-    end
+    visitor.accept_document self
 
     visitor.end_accepting
   end

data/lib/rdoc/markup/formatter.rb

@@ -42,7 +42,12 @@ class RDoc::Markup::Formatter
 
   def accept_document document
     document.parts.each do |item|
-      item.accept self
+      case item
+      when RDoc::Markup::Document then # HACK
+        accept_document item
+      else
+        item.accept self
+      end
     end
   end
 

data/lib/rdoc/markup/heading.rb

@@ -1,7 +1,8 @@
 ##
 # A heading with a level (1-6) and text
 
-class RDoc::Markup::Heading < Struct.new :level, :text
+RDoc::Markup::Heading =
+  Struct.new :level, :text do
 
   @to_html = nil
   @to_label = nil

data/lib/rdoc/markup/to_joined_paragraph.rb

@@ -12,12 +12,15 @@ class RDoc::Markup::ToJoinedParagraph < RDoc::Markup::Formatter
     super nil
   end
 
-  def start_accepting
+  def start_accepting # :nodoc:
   end
 
-  def end_accepting
+  def end_accepting # :nodoc:
   end
 
+  ##
+  # Converts the parts of +paragraph+ to a single entry.
+
   def accept_paragraph paragraph
     parts = []
     string = false

data/lib/rdoc/markup/to_table_of_contents.rb

@@ -18,15 +18,31 @@ class RDoc::Markup::ToTableOfContents < RDoc::Markup::Formatter
 
   attr_reader :res
 
+  ##
+  # Omits headings with a level less than the given level.
+
+  attr_accessor :omit_headings_below
+
   def initialize # :nodoc:
     super nil
+
+    @omit_headings_below = nil
+  end
+
+  ##
+  # Adds +document+ to the output, using its heading cutoff if present
+
+  def accept_document document
+    @omit_headings_below = document.omit_headings_below
+
+    super
   end
 
   ##
   # Adds +heading+ to the table of contents
 
   def accept_heading heading
-    @res << heading
+    @res << heading unless suppressed? heading
   end
 
   ##
@@ -40,9 +56,19 @@ class RDoc::Markup::ToTableOfContents < RDoc::Markup::Formatter
   # Prepares the visitor for text generation
 
   def start_accepting
+    @omit_headings_below = nil
     @res = []
   end
 
+  ##
+  # Returns true if +heading+ is below the display threshold
+
+  def suppressed? heading
+    return false unless @omit_headings_below
+
+    heading.level > @omit_headings_below
+  end
+
   # :stopdoc:
   alias accept_block_quote     ignore
   alias accept_raw             ignore

data/lib/rdoc/options.rb

@@ -228,6 +228,12 @@ class RDoc::Options
 
   attr_accessor :option_parser
 
+  ##
+  # Directory where guides, FAQ, and other pages not associated with a class
+  # live.  You may leave this unset if these are at the root of your project.
+
+  attr_accessor :page_dir
+
   ##
   # Is RDoc in pipe mode?
 
@@ -317,6 +323,7 @@ class RDoc::Options
     @markup = 'rdoc'
     @coverage_report = false
     @op_dir = nil
+    @page_dir = nil
     @pipe = false
     @rdoc_include = []
     @root = Pathname(Dir.pwd)
@@ -468,6 +475,8 @@ class RDoc::Options
       @exclude = Regexp.new(@exclude.join("|"))
     end
 
+    finish_page_dir
+
     check_files
 
     # If no template was specified, use the default template for the output
@@ -481,6 +490,20 @@ class RDoc::Options
     self
   end
 
+  ##
+  # Fixes the page_dir to be relative to the root_dir and adds the page_dir to
+  # the files list.
+
+  def finish_page_dir
+    return unless @page_dir
+
+    @files << @page_dir.to_s
+
+    page_dir = @page_dir.expand_path.relative_path_from @root
+
+    @page_dir = page_dir
+  end
+
   ##
   # Returns a properly-space list of generators and their descriptions.
 
@@ -665,7 +688,7 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
-      opt.on("--pipe",
+      opt.on("--pipe", "-p",
              "Convert RDoc on stdin to HTML") do
         @pipe = true
       end
@@ -708,6 +731,18 @@ Usage: #{opt.program_name} [options] [names...]
         @root = Pathname(root)
       end
 
+      opt.separator nil
+
+      opt.on("--page-dir=DIR", Directory,
+             "Directory where guides, your FAQ or",
+             "other pages not associated with a class",
+             "live.  Set this when you don't store",
+             "such files at your project root.",
+             "NOTE: Do not use the same file name in",
+             "the page dir and the root of your project") do |page_dir|
+        @page_dir = Pathname(page_dir)
+      end
+
       opt.separator nil
       opt.separator "Common generator options:"
       opt.separator nil

data/lib/rdoc/parser.rb

@@ -1,3 +1,5 @@
+# -*- coding: us-ascii -*-
+
 ##
 # A parser is simple a class that subclasses RDoc::Parser and implements #scan
 # to fill in an RDoc::TopLevel with parsed data.
@@ -138,12 +140,38 @@ class RDoc::Parser
     # The default parser must not parse binary files
     ext_name = File.extname file_name
     return parser if ext_name.empty?
-    return if parser == RDoc::Parser::Simple and ext_name !~ /txt|rdoc/
+    if parser == RDoc::Parser::Simple and ext_name !~ /txt|rdoc/ then
+      case check_modeline file_name
+      when 'rdoc' then # continue
+      else return nil
+      end
+    end
 
     parser
   rescue Errno::EACCES
   end
 
+  ##
+  # Returns the file type from the modeline in +file_name+
+
+  def self.check_modeline file_name
+    line = open file_name do |io|
+      io.gets
+    end
+
+    /-\*-\s*(.*?\S)\s*-\*-/ =~ line
+
+    return nil unless type = $1
+
+    if /;/ =~ type then
+      return nil unless /(?:\s|\A)mode:\s*([^\s;]+)/i =~ type
+      type = $1
+    end
+
+    type.downcase
+  rescue ArgumentError # invalid byte sequence, etc.
+  end
+
   ##
   # Finds and instantiates the correct parser for the given +file_name+ and
   # +content+.
@@ -240,6 +268,7 @@ end
 # simple must come first in order to show up last in the parsers list
 require 'rdoc/parser/simple'
 require 'rdoc/parser/c'
+require 'rdoc/parser/changelog'
 require 'rdoc/parser/markdown'
 require 'rdoc/parser/rd'
 require 'rdoc/parser/ruby'