rdoc-markdown 0.20.2 → 0.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 867481b03e8cfa3279b67d5344e3d95dfed1c23b4a885cef33bf2cf0992d2df8
-  data.tar.gz: f1bea8f39ecc1ccfdb9363c8c1071fa01099cf48596c1e4d90b01dee4cd000b1
+  metadata.gz: 5103b919452fc2a8143563d54ce1c2e7ab3e4aaf2afdfe44d6057fcce9a2e5c4
+  data.tar.gz: d8abe423253297371c5cb60c722bb24507c40d2a73ee9df37eca75a1b2dab60a
 SHA512:
-  metadata.gz: 9eb94354e06c97eb71c9bf4defc1c4f4b7f62489d1ac5d9170cb2d091ab126f181b6f84457d9f2f78a324814ed417d78a9dba67f3d2a995cacfabc276cab3eba
-  data.tar.gz: 2caa21c1f0968226a68dddfb115f9dd6c8750ed08db856fb94dce541100eb7b0c2fb36ef7da355f54f5b50e15129c9b65cd19ff5e0aa597e9a65c4a955eb2e33
+  metadata.gz: 3fa2a3b9e6cc98af9902d054f3ad4989e05639f9f55da4bd2d5e4f5a984d9e97833d1c4d06898439a00907ad783ec7329ad46c2c8ae614fcc46a001ceea444fd
+  data.tar.gz: dedabad24735933e97d59127de66271a2a628287822e626c6eb4c5bf9631c613c512a05a511918c4a84fed34bffa61dd29166716fe61ae4badf38fa3e9220deb

data/CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 
-## Unreleased
+## 0.21.1
+
+- Preserve hash-prefixed comments and literal Markdown headings in code examples when offsetting documentation headings.
+
+## 0.21.0
+- Keep generated method and section headings readable after raw HTML descriptions.
+- Validate search-index targets and same-document links against parsed Markdown headings and anchors, including alias targets.
+- Leave alias targets unlinked when RDoc has removed the canonical method from the generated documentation.
+- Preserve literal HTML, ERB templates, heredocs, and entity strings in code examples.
 
 ## 0.20.2
 

data/README.md

@@ -60,6 +60,12 @@ To validate generated markdown against GitHub Flavored Markdown and check local
 rake markdown:validate
 ```
 
+Validation also checks same-document fragment links and every `index.csv` target.
+Indexed fragments and method/attribute links must point to parsed Markdown heading
+sections: an anchor appearing only in a code example or a raw HTML block is not
+enough. This catches method headings swallowed by an unterminated Markdown HTML
+block, including aliases that link back to those methods.
+
 To lint markdown ERB templates:
 
 ```

data/lib/rdoc/generator/markdown/conversion.rb

@@ -9,15 +9,13 @@ class RDoc::Generator::Markdown::Conversion
   #
   # @return [String] Markdown with normalized links and no trailing whitespace.
   def self.markdownify(input, heading_level_offset: 0)
-    fragment = normalized_html_fragment(input)
+    fragment = normalized_html_fragment(input, heading_level_offset)
     anchor_aliases = tokenize_legacy_anchors(fragment.css("span.legacy-anchor[id]"))
     document = fragment.document
     fragment.css("a").each { |link| normalize_link(link, document) }
     markdown = ReverseMarkdown.convert(fragment, github_flavored: true).dup
     markdown.gsub!(Regexp.union(anchor_aliases.keys), anchor_aliases)
-    normalize_definition_list_code_blocks(markdown).rstrip.gsub(/^(#+)(\s)/) do
-      "#{"#" * [Regexp.last_match(1).length + heading_level_offset, 6].min}#{Regexp.last_match(2)}"
-    end
+    normalize_definition_lists(markdown).rstrip
   end
 
   class << self
@@ -26,9 +24,10 @@ class RDoc::Generator::Markdown::Conversion
     # Normalizes HTML constructs that reverse_markdown cannot preserve directly.
     #
     # @param input [String] RDoc HTML fragment.
+    # @param heading_level_offset [Integer] Heading levels to add to actual HTML headings.
     #
     # @return [Nokogiri::HTML4::DocumentFragment] Normalized fragment.
-    def normalized_html_fragment(input)
+    def normalized_html_fragment(input, heading_level_offset)
       fragment = Nokogiri::HTML.fragment(input)
       context_anchors, content_anchors = fragment.css("span.legacy-anchor[id]").partition do |span|
         context_anchor?(span)
@@ -41,7 +40,7 @@ class RDoc::Generator::Markdown::Conversion
       normalize_pre_blocks(fragment)
       document = fragment.document
       fragment.css("h1, h2, h3, h4, h5, h6").each do |heading|
-        normalize_heading_link(heading, document)
+        normalize_heading(heading, document, heading_level_offset)
       end
       fragment
     end
@@ -64,17 +63,19 @@ class RDoc::Generator::Markdown::Conversion
       fragment.css("pre").each do |pre|
         language = pre["class"].to_s[/\A(?!highlight\z)[A-Za-z][A-Za-z0-9_+-]*\z/]
         pre["class"] = "brush: #{language};" if language
-        pre.inner_html = pre.text
+        pre.content = pre.text
       end
     end
 
-    # Normalizes one heading's leading fragment link.
+    # Normalizes one heading's level and leading fragment link.
     #
     # @param heading [Nokogiri::XML::Element] Heading element.
     # @param document [Nokogiri::HTML4::Document] Owning document.
+    # @param heading_level_offset [Integer] Heading levels to add, capped at six.
     #
     # @return [void]
-    def normalize_heading_link(heading, document)
+    def normalize_heading(heading, document, heading_level_offset)
+      heading.name = "h#{[Integer(heading.name.delete_prefix("h")) + heading_level_offset, 6].min}"
       link = heading.xpath("./a[starts-with(@href, '#') and string-length(@href) > 1]").find do |anchor|
         leading_heading_link?(anchor)
       end
@@ -152,14 +153,17 @@ class RDoc::Generator::Markdown::Conversion
         .sub(%r{\A((?:\.\./)*)(?:files|classes|modules)/(?=.+\.md(?:[?#]|\z))}, '\1')
     end
 
-    # Converts RDoc definition-list code blocks into Markdown lists.
+    # Converts RDoc definition-list code blocks into Markdown lists and separates
+    # raw HTML lists from following Markdown without rewriting fenced examples.
     #
     # @param markdown [String] Markdown content.
     #
-    # @return [String] Markdown with convertible blocks normalized.
-    def normalize_definition_list_code_blocks(markdown)
-      markdown.gsub(/```[^\n]*\n(.+?)\n```/m) do
+    # @return [String] Markdown with definition lists normalized.
+    def normalize_definition_lists(markdown)
+      markdown.gsub(%r{```[^\n]*\n(.+?)\n```|</dl>\n(?=\S)}m) do
         body = Regexp.last_match(1)
+        next "</dl>\n\n" unless body
+
         converted = convert_definition_list_block(body)
         converted || Regexp.last_match
       end

data/lib/rdoc/generator/markdown/descriptions.rb

@@ -149,11 +149,13 @@ module RDoc::Generator::Markdown::Descriptions
   # @param method [RDoc::AnyMethod] Target method.
   # @param current_class [RDoc::Context] Class or module currently being rendered.
   #
-  # @return [String, nil] Anchor or relative Markdown link target, or nil when the target page is omitted.
+  # @return [String, nil] Anchor or relative Markdown link target, or nil when the target method or page is omitted.
   def method_link(method, current_class:)
     return unless method.display?
 
     target_parent = method.parent
+    return unless target_parent.method_list.include?(method)
+
     target_path = generation_state.class_output_paths[target_parent.full_name]
     return unless target_path
 

data/lib/rdoc/markdown/version.rb

@@ -5,6 +5,6 @@ module Rdoc
   # @private
   module Markdown
     # @private
-    VERSION = "0.20.2"
+    VERSION = "0.21.1"
   end
 end

data/lib/templates/classfile.md.erb

@@ -29,6 +29,7 @@
 <%- group_heading_level = section_heading_level + 1 -%>
 <%- member_heading_level = group_heading_level + 1 -%>
 <%- unless section_title.empty? -%>
+
 <%= "#" * section_heading_level %> <%= section_title %>
 <%- end -%>
 <%- section_description = section_description(section, heading_level_offset: section_heading_level) -%>
@@ -61,6 +62,7 @@
 
 <%= "#" * group_heading_level %> <%= visibility.capitalize %> <%= type.capitalize %> Methods
 <% methods.each do |method| -%>
+
 <%= "#" * member_heading_level %> `<%= method_signature(method) %>`<%= anchor(method.aref) %>
 <%= method_description(method, current_class: klass, heading_level_offset: member_heading_level) %>
 <% end -%>

metadata

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