rdoc-markdown 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3d1c4068ecf819554e104801cbf461b722e150e0472bb4215ef96a887750e58
-  data.tar.gz: 5de0a95f8b8265b6877a43f85f14ef55f3a4ce7c5bc4bc972b22be104c91d959
+  metadata.gz: 6c8f2f083fa79cfc383a5de5efe80ed2ce86ca5c8820218ae57f9de9427f8e6e
+  data.tar.gz: b9380e6323ce669abc903f3fb29f598cd346f017c565ef4c7f8d48146124184a
 SHA512:
-  metadata.gz: 7a7863e3dbcf54782565a065f2997e90e3d5f4a5985e174f855dbd060c0afe6af9dd29239a08e2a6466690126370ae44d366bce012eb8b4612e3740a78704992
-  data.tar.gz: 71251348e64ae468b1b739925635aae9f79e003d5be8fef71b769fd757d72e532d8489375a2887adf606b433142b23b50ca93756f38eb88e6aaa57b22e344258
+  metadata.gz: 7245acbe5230c82d9209a9203d9c86dfcd18416b1a60b56c574b5c59bbf81a752c388771e81e7cb135d9197620f2bc7f497db3ad33a0d7151ae1032b1f0b8115
+  data.tar.gz: 547ef3178aceffcf1e44ace777f18e97ed4ffc370ab3e99526ebbcebc053eca307c0c57e9f5d739ebc3b8156912c1b9dc13fbb08289408130c1bc38c92d87855

data/CHANGELOG.md

@@ -3,6 +3,17 @@
 
 ## Unreleased
 
+## 0.17.0
+
+- Remove fabricated external namespaces and preserve exact class and module identities across generated paths, index entries, metadata, and links.
+- Avoid broken alias links when the target method is hidden or its owner page is not generated.
+- Preserve localized section bodies, Markdown format, and source location when translating comments.
+- Avoid duplicate unresolved cross-reference warnings during class and module selection.
+
+## 0.16.1
+
+- Fix copying Markdown pages when RDoc receives relative input paths.
+
 ## 0.16.0
 
 - Don't convert markdown files from source folder. Just copy them.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rdoc-markdown (0.16.0)
+    rdoc-markdown (0.17.0)
       csv
       erb
       rdoc (>= 8.0)

data/README.md

@@ -123,7 +123,7 @@ rake vendor:setup:rails
 bundle exec rake test
 ```
 
-The rails harness validates alias rendering, preserved code blocks, file/page links rewritten to markdown, and index stability (no synthetic nested class names).
+The rails harness validates alias rendering, preserved code blocks, file/page links rewritten to markdown, and omission of fabricated external namespaces.
 
 ### Generate vendored docs
 Use rake tasks to generate markdown output for vendored projects:

data/lib/rdoc/generator/markdown.rb

@@ -98,6 +98,7 @@ class RDoc::Generator::Markdown
   def initialize(store, rdoc_options)
     @store = store
     @options = rdoc_options
+    @source_dir = File.expand_path(rdoc_options.root.to_s)
     @markdown_unknown_tags = self.class.validate_markdown_unknown_tags(rdoc_options.markdown_unknown_tags)
   end
 
@@ -151,14 +152,14 @@ class RDoc::Generator::Markdown
 
       @classes.each do |klass|
         csv << [
-          display_name(klass),
+          klass.full_name,
           klass.type.capitalize,
           output_path_for(klass)
         ]
 
         klass.method_list.select(&:display?).each do |method|
           csv << [
-            "#{display_name(klass)}.#{method.name}",
+            "#{klass.full_name}.#{method.name}",
             "Method",
             "#{output_path_for(klass)}##{method.aref}"
           ]
@@ -170,7 +171,7 @@ class RDoc::Generator::Markdown
           .sort
           .each do |const|
             csv << [
-              "#{display_name(klass)}.#{const.name}",
+              "#{klass.full_name}.#{const.name}",
               "Constant",
               "#{output_path_for(klass)}##{const.name}"
             ]
@@ -182,7 +183,7 @@ class RDoc::Generator::Markdown
           .sort
           .each do |attr|
             csv << [
-              "#{display_name(klass)}.#{attr.name}",
+              "#{klass.full_name}.#{attr.name}",
               "Attribute",
               "#{output_path_for(klass)}##{attr.aref}"
             ]
@@ -223,7 +224,7 @@ class RDoc::Generator::Markdown
       out_file = Pathname.new("#{output_dir}/#{page_output_path(page)}")
       out_file.dirname.mkpath
 
-      next FileUtils.cp(page.absolute_name, out_file) if page.relative_name.end_with?(".md", ".markdown")
+      next FileUtils.cp(File.expand_path(page.absolute_name, @source_dir), out_file) if page.relative_name.end_with?(".md", ".markdown")
 
       content = markdownify(render_description(page))
       File.write(out_file, finalize_markdown(
@@ -259,22 +260,13 @@ class RDoc::Generator::Markdown
     "#{dirname}/#{basename}"
   end
 
-  # Returns the normalized display name for a class or module.
-  #
-  # @param code_object [RDoc::Context] Class or module object.
-  #
-  # @return [String] Display name used in headings and the index.
-  def display_name(code_object)
-    class_doc_for(code_object).fetch(:display_name)
-  end
-
   # Returns the canonical Markdown path for a class or module.
   #
   # @param code_object [RDoc::Context] Class or module object.
   #
   # @return [String] Relative Markdown path.
   def output_path_for(code_object)
-    class_doc_for(code_object).fetch(:output_path)
+    turn_to_path(code_object.full_name)
   end
 
   # Renders a class or module reference, linking it when its documentation is emitted.
@@ -284,11 +276,11 @@ class RDoc::Generator::Markdown
   #
   # @return [String] Markdown text or link.
   def metadata_reference(target, label)
-    class_doc = @class_docs_by_name[normalized_full_name(target.full_name)] if target.respond_to?(:full_name)
+    output_path = @class_output_paths[target.full_name] if target.respond_to?(:full_name)
     cell = metadata_table_cell(label)
-    return cell unless class_doc
+    return cell unless output_path
 
-    "[#{cell}](#{class_doc.fetch(:output_path)})"
+    "[#{cell}](#{output_path})"
   end
 
   # Escapes text for a Markdown table cell.
@@ -389,16 +381,31 @@ class RDoc::Generator::Markdown
   #
   # @param code_object [RDoc::CodeObject, RDoc::Context::Section] Object whose description is rendered.
   #
-  # @return [String, nil] HTML description, or nil for an empty section.
+  # @return [String] HTML description.
   def render_description(code_object)
-    return if RDoc::Context::Section === code_object && code_object.comments.empty?
-
-    formatter = code_object.formatter
+    section = RDoc::Context::Section === code_object
+    formatter = if section
+      code_object.parent.formatter.dup.tap { |copy| copy.code_object = code_object }
+    else
+      code_object.formatter
+    end
     formatter.extend(CrossrefExtension)
     begin
       formatter.markdown_cross_reference = RDoc::CrossReference.new(formatter.context)
       formatter.markdown_output_object_ids = @markdown_output_object_ids
-      code_object.description
+      if section
+        locale = options.locale
+        documents = code_object.comments.map do |comment|
+          next comment.parse unless locale && !comment.text.empty?
+
+          comment = comment.dup
+          comment.text = RDoc::I18n::Text.new(comment).translate(locale)
+          comment.parse
+        end
+        RDoc::Markup::Document.new(*documents).accept(formatter)
+      else
+        code_object.description
+      end
     ensure
       formatter.markdown_cross_reference = nil
     end
@@ -584,7 +591,10 @@ class RDoc::Generator::Markdown
     aliased_method = method.is_alias_for
     return "Not documented." unless aliased_method
 
-    "Alias for: [`#{aliased_method.name}`](#{method_link(aliased_method, current_class: current_class)})"
+    link = method_link(aliased_method, current_class: current_class)
+    return "Alias for: `#{aliased_method.name}`" unless link
+
+    "Alias for: [`#{aliased_method.name}`](#{link})"
   end
 
   # Applies final whitespace and link normalization before writing Markdown.
@@ -661,12 +671,16 @@ class RDoc::Generator::Markdown
   # @param method [RDoc::AnyMethod] Target method.
   # @param current_class [RDoc::Context] Class or module currently being rendered.
   #
-  # @return [String] Anchor or relative Markdown link target.
+  # @return [String, nil] Anchor or relative Markdown link target, or nil when the target page is omitted.
   def method_link(method, current_class:)
+    return unless method.display?
+
     target_parent = method.parent
+    target_path = @class_output_paths[target_parent.full_name]
+    return unless target_path
     return "##{method.aref}" if target_parent == current_class
 
-    "#{output_path_for(target_parent)}##{method.aref}"
+    "#{target_path}##{method.aref}"
   end
 
   # Rewrites local Markdown links relative to the current output file.
@@ -719,7 +733,7 @@ class RDoc::Generator::Markdown
   def normalize_input_path_for_output(path)
     normalized = path.tr("\\", "/").sub(%r{\A\./}, "")
 
-    root = File.expand_path(@options.root.to_s)
+    root = @source_dir
     normalized = normalized.sub(%r{\A#{Regexp.escape(root)}/}, "")
     normalized = normalized.sub(%r{\A/}, "")
 
@@ -727,117 +741,6 @@ class RDoc::Generator::Markdown
     normalized.sub(%r{\A#{Regexp.escape(root_basename)}/}, "")
   end
 
-  # Looks up resolved class documentation metadata.
-  #
-  # @param code_object [RDoc::Context] Class or module object.
-  #
-  # @return [Hash{Symbol => Object}] Metadata for rendering the object.
-  def class_doc_for(code_object)
-    @class_docs_by_object_id.fetch(code_object.object_id)
-  end
-
-  # Builds canonical class documentation metadata from RDoc objects.
-  #
-  # @param classes [Array<RDoc::Context>] Classes and modules to normalize.
-  #
-  # @return [Array<Hash{Symbol => Object}>] Metadata ordered by display name.
-  def build_class_docs(classes)
-    docs_by_name = {}
-
-    classes.select(&:display?).each do |klass|
-      display_name = normalized_full_name(klass.full_name)
-      output_path = turn_to_path(display_name)
-      score = class_content_score(klass)
-
-      candidate = {
-        klass: klass,
-        display_name: display_name,
-        output_path: output_path,
-        score: score
-      }
-
-      existing = docs_by_name[display_name]
-
-      if existing.nil?
-        docs_by_name[display_name] = candidate
-      elsif candidate.fetch(:score) > existing.fetch(:score)
-        docs_by_name[display_name] = candidate
-      end
-    end
-
-    docs_by_name.values
-      .select do |doc|
-        klass = doc.fetch(:klass)
-
-        doc.fetch(:score).positive? ||
-          (!class_has_raw_members?(klass) && !synthetic_full_name?(klass.full_name))
-      end
-      .sort_by { |doc| doc.fetch(:display_name) }
-  end
-
-  # Collapses repeated namespace segments from synthetic vendored names.
-  #
-  # @param full_name [String] Full RDoc object name.
-  #
-  # @return [String] Normalized object name.
-  def normalized_full_name(full_name)
-    normalized = full_name
-
-    loop do
-      if normalized =~ /\A([^:]+)(?:::[^:]+)+::\1::(.+)\z/
-        normalized = "#{Regexp.last_match(1)}::#{Regexp.last_match(2)}"
-      end
-
-      if normalized =~ /\A(.+?)::\1\z/
-        normalized = Regexp.last_match(1)
-      end
-
-      break
-    end
-
-    normalized
-  end
-
-  # Scores how much owned content a class or module has.
-  #
-  # @param klass [RDoc::Context] Class or module object.
-  #
-  # @return [Integer] Content score used to choose duplicate docs.
-  def class_content_score(klass)
-    score = class_member_count(klass)
-    score += 1 unless klass.description.empty?
-    score
-  end
-
-  # Counts methods, constants, and attributes owned by a class or module.
-  #
-  # @param klass [RDoc::Context] Class or module object.
-  #
-  # @return [Integer] Number of owned members.
-  def class_member_count(klass)
-    klass.method_list.count(&:display?) + klass.constants.count(&:display?) + klass.attributes.count(&:display?)
-  end
-
-  # Checks whether a class or module owns any members before display filtering.
-  #
-  # @param klass [RDoc::Context] Class or module object.
-  #
-  # @return [Boolean] True when any owned member exists before display filtering.
-  def class_has_raw_members?(klass)
-    klass.method_list.any? || klass.constants.any? || klass.attributes.any?
-  end
-
-  # Checks whether a name appears to contain duplicated root namespaces.
-  #
-  # @param full_name [String] Full RDoc object name.
-  #
-  # @return [Boolean] True when the root namespace appears more than once.
-  def synthetic_full_name?(full_name)
-    parts = full_name.split("::")
-    root = parts.first
-    parts.count(root) > 1
-  end
-
   # Prepares sorted objects and link lookup state for generation.
   #
   # @return [void]
@@ -847,13 +750,19 @@ class RDoc::Generator::Markdown
       raise TypeError, "RDoc markdown output directory must be a String"
     end
 
-    @class_docs = build_class_docs(@store.all_classes_and_modules.sort)
-    @class_docs_by_object_id = @class_docs.to_h { |doc| [doc.fetch(:klass).object_id, doc] }
-    @class_docs_by_name = @class_docs.to_h { |doc| [doc.fetch(:display_name), doc] }
-    @classes = @class_docs.map { |doc| doc.fetch(:klass) }
+    @classes = @store.unique_classes_and_modules.select(&:display?).select do |klass|
+      klass.in_files.any? ||
+        klass.documented? ||
+        klass.includes.any? ||
+        klass.method_list.any?(&:display?) ||
+        klass.constants.any?(&:display?) ||
+        klass.attributes.any?(&:display?) ||
+        klass.sections.any? { |section| section.title.to_s.match?(/\S/) || !section.to_document.empty? }
+    end.sort
+    @class_output_paths = @classes.to_h { |klass| [klass.full_name, output_path_for(klass)] }
     @pages = @store.all_files.select(&:text?).select(&:display?).sort_by(&:base_name)
     @markdown_output_object_ids = (@classes + @pages).map(&:object_id)
-    @known_output_paths = @class_docs.map { |doc| doc.fetch(:output_path) }
+    @known_output_paths = @class_output_paths.values
     @pages.each { |page| @known_output_paths << page_output_path(page) }
 
     @root_path_segment = Pathname.new(@options.root || ".").basename

data/lib/rdoc/markdown/version.rb

@@ -5,6 +5,6 @@ module Rdoc
   # @private
   module Markdown
     # @private
-    VERSION = "0.16.0"
+    VERSION = "0.17.0"
   end
 end

data/lib/templates/classfile.md.erb

@@ -1,4 +1,4 @@
-# <%= klass.type.capitalize %> <%= display_name(klass) %><%= anchor(klass.aref.strip) %>
+# <%= klass.type.capitalize %> <%= klass.full_name %><%= anchor(klass.aref.strip) %>
 <%- superclass = klass.superclass if klass.type == "class" -%>
 <%- includes = klass.includes -%>
 <%- source_files = klass.in_files -%>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rdoc-markdown
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov