rdoc-markdown 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 575534e13c6e1b37284625867c6d57661f8af184308ce3a926b482025d964248
-  data.tar.gz: 68165f940dd78b6da93cea34cf0ed52b85c25d9616226326959e1dd66dcbbe8e
+  metadata.gz: 7fb0eeb24c5e69e9a8cc6b5f41f9e83cc8669da4f7f3282c08a8347021536135
+  data.tar.gz: f36ab292793914871d6bc119493c02bbbe94cb90944ececa98be56b4db7f0446
 SHA512:
-  metadata.gz: 1e9cd00c3f59f79153e01fb666801615d9a30c486c3c3bdf10c0e73e7118b2badda559e661f2f73cb9741fc6b2e6a8d44946a4ff3210f4ee1e74acf44a82c5b6
-  data.tar.gz: faef36b7139ea5ffd5f2b959aaf522e47cc254f54bf3a1622ccb56c64936bb4e22b5c17cb8f2d323ad6b5691b32c63d8586cf71c756cabb4136568d5a78663b2
+  metadata.gz: 5430c965fb823c2e5c384e67d9cc8d9cd91a08749b089ee486d5868bd97d6a4aa9cad417c4ff03028c69ae2ebb5ccc62e50698490d8d6be8c3bd57049ebcb40a
+  data.tar.gz: e016dfb4a279a0c8283d3455098a84c9f68d4817fbb23cafdf3c1ed2f00b1de9683a2b6a81a161a47321692c07684c5b97c8658ec21cbac0f0647d3a51132137

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.13.0
+
+- Adding metadata to classes/modules
+- Fixed: cross-linking between markdown files
+
+## 0.12.1
+
+- simplification: automatic root-page inclusion hook.
+- Explicit RDoc file lists are authoritative again; unlisted README, CHANGELOG, and similar files are not silently added.
+
+## 0.12.0
+
+- Indexing: Classifies root-level README and GUIDE pages as Readme.
+- Indexing: Classifies root-level CHANGELOG and HISTORY pages as Changelog.
+- Recognizes .rdoc, .md, and .markdown, case-insensitively by basename.
+
 ## 0.11.1
 
 - Changed headings from standalone anchors to adjacent inline anchors:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rdoc-markdown (0.12.0)
+    rdoc-markdown (0.13.0)
       csv
       erb
       rdoc

data/lib/rdoc/generator/markdown.rb

@@ -26,7 +26,7 @@ class RDoc::Generator::Markdown
     "history" => "Changelog"
   }
 
-  # Source page extensions RDoc should auto-include from the root directory.
+  # Source page extensions eligible for root page classification.
   ROOT_PAGE_EXTENSIONS = %w[.rdoc .md .markdown]
 
   # Returns the configured search-index type for an eligible root text page path.
@@ -75,30 +75,6 @@ class RDoc::Generator::Markdown
       super
       @markdown_unknown_tags = map.fetch("markdown_unknown_tags") if map.key?("markdown_unknown_tags")
     end
-
-    # Adds markdown root entry pages to explicit source files.
-    #
-    # @return [void]
-    def check_files
-      return super unless @generator == RDoc::Generator::Markdown
-      super
-      return if @files.empty?
-
-      root = Pathname(@root)
-      expanded_root = root.expand_path
-      expanded_files = @files.map { |file| Pathname(file).expand_path.to_s }
-      @files.concat(
-        Dir.children(expanded_root).filter_map do |name|
-          path = expanded_root.join(name)
-          next unless path.file?
-          next unless File.readable?(path)
-          next unless RDoc::Generator::Markdown.root_page_type_for(name)
-          next if expanded_files.include?(path.to_s)
-
-          root.join(name).to_s
-        end
-      )
-    end
   end
 
   # Registers markdown generator-specific RDoc options.
@@ -276,16 +252,17 @@ class RDoc::Generator::Markdown
     template = ERB.new(template_content, trim_mode: "-")
 
     @classes.each do |klass|
-      result = finalize_markdown(template.result(binding), current_output_path: output_path_for(klass))
-
-      out_file = Pathname.new("#{output_dir}/#{output_path_for(klass)}")
-      out_file.dirname.mkpath
-      File.write(out_file, result)
-
-      legacy_paths_for(klass).each do |legacy_path|
-        legacy_file = Pathname.new("#{output_dir}/#{legacy_path}")
-        legacy_file.dirname.mkpath
-        File.write(legacy_file, result)
+      content = template.result(binding)
+      output_path = output_path_for(klass)
+
+      ([output_path] | legacy_paths_for(klass)).each do |destination_path|
+        out_file = Pathname.new("#{output_dir}/#{destination_path}")
+        out_file.dirname.mkpath
+        File.write(out_file, finalize_markdown(
+          content,
+          canonical_output_path: output_path,
+          current_output_path: destination_path
+        ))
       end
     end
   end
@@ -299,7 +276,11 @@ class RDoc::Generator::Markdown
       out_file.dirname.mkpath
 
       content = markdownify(page.description)
-      File.write(out_file, finalize_markdown(content, current_output_path: page_output_path(page)))
+      File.write(out_file, finalize_markdown(
+        content,
+        canonical_output_path: page_output_path(page),
+        current_output_path: page_output_path(page)
+      ))
     end
   end
 
@@ -374,6 +355,30 @@ class RDoc::Generator::Markdown
     class_doc_for(code_object).fetch(:legacy_paths)
   end
 
+  # Renders a class or module reference, linking it when its documentation is emitted.
+  #
+  # @param target [RDoc::ClassModule, String] Resolved RDoc object or unresolved name.
+  # @param label [String] Visible reference text.
+  #
+  # @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)
+    cell = metadata_table_cell(label)
+    return cell unless class_doc
+
+    "[#{cell}](#{class_doc.fetch(:output_path)})"
+  end
+
+  # Escapes text for a Markdown table cell.
+  #
+  # @param value [String] Metadata text.
+  #
+  # @return [String] GFM table-safe Markdown text.
+  def metadata_table_cell(value)
+    value.gsub(/[[:blank:]]*\R[[:blank:]]*/, " ")
+      .gsub(/[\x21-\x2F\x3A-\x40\x5B-\x60\x7B-\x7E]/) { |character| "\\#{character}" }
+  end
+
   # Converts RDoc HTML into GitHub-flavored Markdown.
   #
   # @param input [String] RDoc HTML fragment.
@@ -612,12 +617,17 @@ class RDoc::Generator::Markdown
   # Applies final whitespace and link normalization before writing Markdown.
   #
   # @param content [String] Markdown content.
+  # @param canonical_output_path [String] Canonical output path used to resolve links.
   # @param current_output_path [String] Output path for the file being written.
   #
   # @return [String] Final Markdown ending with one newline.
-  def finalize_markdown(content, current_output_path:)
+  def finalize_markdown(content, canonical_output_path:, current_output_path:)
     output = content.lines.map(&:rstrip).join("\n")
-    output = normalize_internal_links(output, current_output_path: current_output_path)
+    output = normalize_internal_links(
+      output,
+      canonical_output_path: canonical_output_path,
+      current_output_path: current_output_path
+    )
     output = output.sub(/\n{3,}/, "\n\n")
     "#{output}\n"
   end
@@ -694,10 +704,12 @@ class RDoc::Generator::Markdown
   # Rewrites local Markdown links relative to the current output file.
   #
   # @param markdown [String] Markdown content.
+  # @param canonical_output_path [String] Canonical output path used to resolve links.
   # @param current_output_path [String] Output path for the file being written.
   #
   # @return [String] Markdown with normalized internal links.
-  def normalize_internal_links(markdown, current_output_path:)
+  def normalize_internal_links(markdown, canonical_output_path:, current_output_path:)
+    canonical_dir = Pathname.new(canonical_output_path).dirname
     current_dir = Pathname.new(current_output_path).dirname
 
     markdown.gsub(%r{\]\(([^)]+)\)}) do
@@ -705,7 +717,7 @@ class RDoc::Generator::Markdown
       path = target.sub(/[?#].*\z/, "")
       suffix = target[path.length..]
 
-      resolved = resolve_output_path(path, current_dir)
+      resolved = resolve_output_path(path, canonical_dir)
       rewritten = resolved ? Pathname.new(resolved).relative_path_from(current_dir) : path
       "](#{rewritten}#{suffix})"
     end
@@ -877,6 +889,7 @@ class RDoc::Generator::Markdown
 
     @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) }
     @pages = @store.all_files.select(&:text?).select(&:display?).sort_by(&:base_name)
     @rbs_method_signatures = RbsSignatureIndex.build(Array(@options.files), @base_dir, @store)

data/lib/rdoc/markdown/version.rb

@@ -5,6 +5,6 @@ module Rdoc
   # @private
   module Markdown
     # @private
-    VERSION = "0.12.0"
+    VERSION = "0.13.0"
   end
 end

data/lib/templates/classfile.md.erb

@@ -1,4 +1,22 @@
 # <%= klass.type.capitalize %> <%= display_name(klass) %><%= anchor(klass.aref.strip) %>
+<%- superclass = klass.superclass if klass.type == "class" -%>
+<%- includes = klass.includes -%>
+<%- source_files = klass.in_files -%>
+<%- if superclass || !includes.empty? || !source_files.empty? -%>
+
+|  |  |
+| --- | --- |
+<%- if superclass -%>
+| **Inherits** | <%= metadata_reference(superclass, superclass.respond_to?(:full_name) ? superclass.full_name : superclass) %> |
+<%- end -%>
+<%- unless includes.empty? -%>
+| **Includes** | <%= includes.map { |mixin| metadata_reference(mixin.module, mixin.name) }.join(", ") %> |
+<%- end -%>
+<%- unless source_files.empty? -%>
+| **Defined in** | <%= source_files.map { |file| metadata_table_cell(file.relative_name) }.join(", ") %> |
+<%- end -%>
+<%- end -%>
+
 <%- class_description = describe(klass) -%>
 <%- unless class_description.empty? -%>
 <%= class_description %>

metadata

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