rdoc-markdown 0.20.1 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ae68a40db5d99f60034820bab835a6a6d17c9db00dd3d38d3d47bd7da73743b
-  data.tar.gz: 65a59f988b16411b5914dc5d7de8496efac2a12a67b835ac50b9fa478c1492fd
+  metadata.gz: 8b215eca69feb6c88372f2a84436dff0c42712e0f3deb7086c91e9ee1f0e8cd3
+  data.tar.gz: 3ce6ccaeecfd189da39207c07e6f6733c5f183589eb90a3474ea3316b80c0445
 SHA512:
-  metadata.gz: c8c080f1704dff5d1a4ca256676fbf5f1a69d51a9ec0223e952cceb37837f840274a2bb39e44c70801379ef72d7a70d3811e96810de1d5a568341f6ec2a74875
-  data.tar.gz: 10a07e634578b0ac0290d91e4b1f52f6af36e0cb30349fa8d519970020b55246e719dec427f64c8ad59f6505def782e8709e98b6ff4be01f5494637af5cb265c
+  metadata.gz: 5cc5f170e0eae86a2f5ba510db36fb9f1bf5b1eca91d7b3a31fb95f1a0b2188ff8d1b48892fb98c65bfa2b7b46e9d80cbe5c852595e540f214204d0a9d3c936f
+  data.tar.gz: 3df4e291559a57ca7cf727e1e59b60ae8c292cd6defadb7a0c8cef91e1bd56f504e8ab9072d75a9978658efd19b8a0613b7884352ce57cd7cd5d67143762f322

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+- 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
+
+- Preserve documented bracket lookup and assignment arguments in method headings without changing their anchors.
+
 ## 0.20.1
 
 - Don't offset headings for commets 

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

@@ -15,7 +15,7 @@ class RDoc::Generator::Markdown::Conversion
     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
+    normalize_definition_lists(markdown).rstrip.gsub(/^(#+)(\s)/) do
       "#{"#" * [Regexp.last_match(1).length + heading_level_offset, 6].min}#{Regexp.last_match(2)}"
     end
   end
@@ -64,7 +64,7 @@ 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
 
@@ -152,14 +152,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/generator/markdown/signatures.rb

@@ -11,34 +11,54 @@ module RDoc::Generator::Markdown::Signatures
   #
   # @param method [RDoc::AnyMethod] Method object to render.
   #
-  # @return [String] Normalized method signature.
+  # @return [String] Complete signature including the method name or documented receiver.
   def method_signature(method)
     RDoc::Generator::Markdown::Signatures.render_method_signature(method, store)
   end
 
   private :method_signature
 
-  # Builds a method signature from RDoc and store metadata.
+  # Builds a complete method heading signature from RDoc and store metadata.
   #
   # @param method [RDoc::AnyMethod] Method object to render.
   # @param store [RDoc::Store] Documentation store with sidecar signatures.
   #
-  # @return [String] Normalized method signature.
+  # @return [String] Complete signature including the method name or documented receiver.
   def self.render_method_signature(method, store)
-    signatures = method.type_signature_lines || store.rbs_signature_for(method) || [method.param_seq]
+    signatures = method.type_signature_lines || store.rbs_signature_for(method)
+    if !signatures && (call_seq = bracket_call_sequence(method))
+      return call_seq.lines.map { |line| normalize_signature(line) }.join(" | ")
+    end
+    signatures ||= [method.param_seq]
 
     signatures = signatures.filter_map do |signature|
       next unless signature&.match?(/\S/)
 
-      signature = signature.gsub("->", " -> ")
-      signature = signature.gsub(/\s+/, " ").strip
+      signature = normalize_signature(signature)
       signature = " #{signature}" if signature.start_with?("->")
       merge_method_signature_arguments(signature, method.params)
     end
 
-    return "()" if signatures.empty?
+    signature = signatures.empty? ? "()" : signatures.join(" | ")
+    "#{method.name}#{signature}"
+  end
 
-    signatures.join(" | ")
+  # Returns the original call syntax for bracket operators, when documented.
+  #
+  # @param method [RDoc::AnyMethod] Method object to render.
+  #
+  # @return [String, nil] Documented bracket calls, or nil for other signatures.
+  def self.bracket_call_sequence(method)
+    method.call_seq if ["[]", "[]="].include?(method.name)
+  end
+
+  # Normalizes spacing in a signature without changing its call syntax.
+  #
+  # @param signature [String] Signature or complete call sequence.
+  #
+  # @return [String] Signature with consistent arrow and whitespace formatting.
+  def self.normalize_signature(signature)
+    signature.gsub("->", " -> ").gsub(/\s+/, " ").strip
   end
 
   # Merges RDoc parameter names into a type-only signature.

data/lib/rdoc/markdown/version.rb

@@ -5,6 +5,6 @@ module Rdoc
   # @private
   module Markdown
     # @private
-    VERSION = "0.20.1"
+    VERSION = "0.21.0"
   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,7 +62,8 @@
 
 <%= "#" * group_heading_level %> <%= visibility.capitalize %> <%= type.capitalize %> Methods
 <% methods.each do |method| -%>
-<%= "#" * member_heading_level %> `<%= method.name %><%= method_signature(method) %>`<%= anchor(method.aref) %>
+
+<%= "#" * member_heading_level %> `<%= method_signature(method) %>`<%= anchor(method.aref) %>
 <%= method_description(method, current_class: klass, heading_level_offset: member_heading_level) %>
 <% end -%>
 <% end -%>

metadata

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