rdoc-markdown 0.21.1 → 0.22.0

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

@@ -1,200 +0,0 @@
-# frozen_string_literal: true
-
-# Converts RDoc HTML and normalizes generated Markdown.
-class RDoc::Generator::Markdown::Conversion
-  # Converts RDoc HTML into GitHub-flavored Markdown.
-  #
-  # @param input [String] RDoc HTML fragment.
-  # @param heading_level_offset [Integer] Heading levels to add.
-  #
-  # @return [String] Markdown with normalized links and no trailing whitespace.
-  def self.markdownify(input, heading_level_offset: 0)
-    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_lists(markdown).rstrip
-  end
-
-  class << self
-    private
-
-    # 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, heading_level_offset)
-      fragment = Nokogiri::HTML.fragment(input)
-      context_anchors, content_anchors = fragment.css("span.legacy-anchor[id]").partition do |span|
-        context_anchor?(span)
-      end
-      context_anchors.each(&:remove)
-      content_anchors.each do |span|
-        heading = span.next_element
-        heading.add_child(span) if heading&.name&.match?(/\Ah[1-6]\z/)
-      end
-      normalize_pre_blocks(fragment)
-      document = fragment.document
-      fragment.css("h1, h2, h3, h4, h5, h6").each do |heading|
-        normalize_heading(heading, document, heading_level_offset)
-      end
-      fragment
-    end
-
-    # Checks whether an anchor identifies the surrounding class or module.
-    #
-    # @param span [Nokogiri::XML::Element] Legacy anchor span.
-    #
-    # @return [Boolean] Whether the anchor belongs to a top-level context heading.
-    def context_anchor?(span)
-      span.next_element&.name == "h1" && span["id"].match?(/\A(?:class|module)-/)
-    end
-
-    # Preserves simple language classes and literal preformatted text.
-    #
-    # @param fragment [Nokogiri::HTML4::DocumentFragment] HTML fragment.
-    #
-    # @return [void]
-    def normalize_pre_blocks(fragment)
-      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.content = pre.text
-      end
-    end
-
-    # 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(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
-      return unless link
-
-      id = link["href"].delete_prefix("#")
-      link.replace(link.children)
-      return if id == RDoc::Text.to_anchor(heading.text)
-
-      heading.add_child(document.create_element("span", "class" => "legacy-anchor", "id" => id))
-    end
-
-    # Checks whether a link is the first visible content in its heading.
-    #
-    # @param anchor [Nokogiri::XML::Element] Candidate heading link.
-    #
-    # @return [Boolean] Whether no visible text precedes the link.
-    def leading_heading_link?(anchor)
-      anchor.text.match?(/\S/) &&
-        anchor.xpath("preceding-sibling::node()").none? { |sibling| sibling.text.match?(/\S/) }
-    end
-
-    # Replaces legacy anchors with tokens that survive reverse_markdown.
-    #
-    # @param anchors [Nokogiri::XML::NodeSet] Legacy anchor spans.
-    #
-    # @return [Hash{String => String}] Token-to-anchor HTML lookup.
-    def tokenize_legacy_anchors(anchors)
-      anchors.each.with_index.to_h do |span, index|
-        token = "RDocMarkdownAnchor#{index}End"
-        anchor = %(<a id="#{span["id"]}"></a>)
-        span.replace(token)
-        [token, anchor]
-      end
-    end
-
-    # Normalizes one HTML link.
-    #
-    # @param link [Nokogiri::XML::Element] Link element.
-    # @param document [Nokogiri::HTML4::Document] Owning document.
-    #
-    # @return [void]
-    def normalize_link(link, document)
-      receiver = link.text
-      href = link["href"].to_s
-
-      if index_reference?(receiver, href)
-        link.replace(document.create_element("code") { |code| code.content = "#{receiver}[#{href}]" })
-      elsif href.start_with?("www.")
-        link["href"] = "https://#{href}"
-      elsif !href.match?(/\A(?:https?:\/\/|mailto:|#)/i)
-        link["href"] = normalized_link_target(href)
-      end
-    end
-
-    # Checks whether RDoc encoded an indexing expression as a link.
-    #
-    # @param receiver [String] Visible receiver text.
-    # @param href [String] Link target.
-    #
-    # @return [Boolean] Whether the link represents Ruby indexing syntax.
-    def index_reference?(receiver, href)
-      receiver.match?(/\A(?:[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*|[a-z_][A-Za-z0-9_]*)\z/) &&
-        href.match?(/\A(?::.+|".+")\z/)
-    end
-
-    # Rewrites an internal RDoc HTML target to its Markdown equivalent.
-    #
-    # @param href [String] Original link target.
-    #
-    # @return [String] Normalized target.
-    def normalized_link_target(href)
-      href.sub(/\.html(?=[?#]|\z)/i, ".md")
-        .sub(%r{\A/(?=.+\.md(?:[?#]|\z))}, "")
-        .sub(%r{\A((?:\.\./)*)(?:files|classes|modules)/(?=.+\.md(?:[?#]|\z))}, '\1')
-    end
-
-    # 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 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
-    end
-
-    # Converts a single definition-list code block.
-    #
-    # @param body [String] Code block body.
-    #
-    # @return [String, nil] Converted Markdown, or nil when the block is not a definition list.
-    def convert_definition_list_block(body)
-      lines = body.lines
-      return nil unless lines.all? { |line| definition_list_line?(line) }
-
-      lines.map do |line|
-        stripped = line.strip
-        next if stripped.empty?
-        next "#{stripped.sub(/::\z/, "")}:" if stripped.end_with?("::")
-
-        "- #{stripped.sub(/\A\*\s/, "")}"
-      end.join("\n")
-    end
-
-    # Checks whether a line can appear in a converted definition list.
-    #
-    # @param line [String] Markdown line.
-    #
-    # @return [Boolean] True when the line matches RDoc definition-list output.
-    def definition_list_line?(line)
-      stripped = line.strip
-      stripped.empty? || stripped.end_with?("::") || stripped.match?(/\A\*\s/)
-    end
-  end
-end

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

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-# Prevents RDoc from linking to code objects omitted from Markdown output.
-module RDoc::Generator::Markdown::CrossrefExtension
-  # Applies Markdown cross-reference state while rendering a description.
-  #
-  # @param cross_reference [RDoc::CrossReference] Resolver scoped to the formatter.
-  # @param output_object_ids [Set<Integer>] Object IDs emitted by the generator.
-  #
-  # @return [Object] Value returned by the block.
-  def with_markdown_cross_references(cross_reference, output_object_ids)
-    @markdown_cross_reference = cross_reference
-    @markdown_output_object_ids = output_object_ids
-    yield
-  ensure
-    @markdown_cross_reference = nil
-  end
-
-  # Renders a cross-reference only when its owning object is emitted.
-  #
-  # @param name [String, nil] Cross-reference target.
-  # @param text [String] Visible link text.
-  # @param code [Boolean] Whether to format code objects as code.
-  # @param rdoc_ref [Boolean] Whether the target uses the rdoc-ref scheme.
-  #
-  # @return [String] HTML link or unlinked text.
-  def link(name, text, code = true, rdoc_ref: false)
-    return super unless @markdown_cross_reference
-
-    ref = @markdown_cross_reference.resolve(name) if name
-    return super unless RDoc::CodeObject === ref
-
-    context = ref
-    context = context.parent until RDoc::ClassModule === context || RDoc::TopLevel === context
-    return super if @markdown_output_object_ids.include?(context.object_id)
-
-    return text if RDoc::TopLevel === ref || !code
-
-    "<code>#{text}</code>"
-  end
-end