rdoc-markdown 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6769180d689a0858bfe6af579ea16ae9bbe1a4aa8ff6471bdf0e145731a3621b
-  data.tar.gz: 4e9c43e702b50a7e894f1cea99418c1c3e0d9c1070ec9b5b41fa8dc654e97df6
+  metadata.gz: 7c5f77f880bb2c5dee60d22aaec8c1ed37e2525234afab66983549482406e321
+  data.tar.gz: c395b71591e6c71e16ef766cd6b389eb47a3c520dd859c6605b3540b30e98b83
 SHA512:
-  metadata.gz: 17214dddbe75a0f4496e3ab7d818b005ebfc800bb6d9c11b6c8e946f36d409054b898024f332dddb7b99025cf6704a429ad723e5d0205c34a5d264c4cf019e2f
-  data.tar.gz: 180c0790a847153dd2368c273e721a92ce6cea08119cd2d2445d5a0a88c609ae7d5a074753916a56e4f61307ad370d7f2dcc0345983de9c008bc1c6c7e0cefd4
+  metadata.gz: 39fca2d4e12f36652b1991d6bbada634b1f7b3d2280c1d39c9a0dce6398aa7210384d1451ff43797f9fd09bdf897fc14ff92b0b2c20159bf74653c2a27da24c6
+  data.tar.gz: 90fb4b652886f2f8da0637ac102ec728bd457c9eb49b77b27e542afe945b5da211a5b57a3b860c4edc711f57a6a5ce8a121bff73ae542daad051a57356ac348f

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.19.0
+
+- Remove the `markdown_unknown_tags` option and use reverse_markdown's default handling.
+- Preserve source file extensions in search-index names.
+
 ## 0.18.0
 
 - Rework heading for the document

data/README.md

@@ -2,63 +2,35 @@
 RDoc plugin to generate markdown documentation and search index file (CSV).
 
 > [!CAUTION]
-> This gem relies on multiple hacks to generate "plausible" markdown documentation. This is **NOT PRODUCTION READY**, use at your own risk.
+> This gem relies on multiple hacks to generate "plausible" markdown documentation. This is **NOT PRODUCTION READY** — use at your own risk.
 >
-> rdoc maintainers are actively working on markdown support, things will improve with time... 
+> RDoc maintainers are actively working on markdown support, things will improve with time...
 
 ## Motivation
-Markdown has become the de-facto documentation standard. We can render markdown file on any device, possibly on thermometer with a screen. And everyone knows markdown...
+Markdown has become the de facto documentation standard. We can render markdown files on any device, possibly on a thermometer with a screen. And everyone knows markdown...
 
-It's a pitty that rdoc can't output a proper markdown file. Somebody has to try and build it.
+It's a pity that RDoc can't output a proper markdown file. Somebody has to try to build it.
 
 ## Installation
 
 rdoc-markdown requires Ruby 3.3 or newer and RDoc 8 or newer.
 
-Install gem and add to application's Gemfile by executing:
+Install the gem and add it to your application's Gemfile by executing:
 
     $ bundle add rdoc-markdown
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+If Bundler is not being used to manage dependencies, install the gem by executing:
 
     $ gem install rdoc-markdown
-## Examples
-Find examples in [/example](/example/) folder. You can regenerate examples by running `./bin/generate.sh`; it produces the sample docs from `test/data/example.rb` and a pinned `jekyll-seo-tag` example from `vendor/jekyll-seo-tag`.
 
 
 ## Usage
-RDoc will auto-detect rdoc-markdown plugin if it was installed. You just need to instruct RDoc to produce markdown output instead of standard HTML through `format` parameter.
+RDoc will auto-detect the rdoc-markdown plugin if it is installed. You just need to instruct RDoc to produce markdown output instead of standard HTML through the `format` parameter.
 
-Run following command in directory with ruby source code:
+Run the following command in a directory with Ruby source code:
 
 `rdoc --format=markdown`
 
-This will produce a tree of markdown documents and search index in `/doc` folder. Every class in library will have it's own markdown file.
-
-Input `.md` and `.markdown` pages are copied unchanged to the same relative path. RDoc pages and Ruby documentation are converted to Markdown.
-
-### Unknown HTML tags
-rdoc-markdown uses `reverse_markdown` to convert RDoc's HTML fragments to Markdown. You can configure how unknown HTML tags are handled with:
-
-```sh
-rdoc --format=markdown --markdown-unknown-tags=raise
-```
-
-Accepted values are `pass_through`, `drop`, `bypass`, and `raise`. The default is `pass_through`.
-
-The same setting can be stored in RDoc's `.rdoc_options` file:
-
-```yaml
----
-markdown_unknown_tags: :raise
-```
-
-## Note on index.csv file
-This gem emits index of all markdown files in a index.csv file.
-
-There are decent tools that offer search through structured plain-text files. But my expectation is that nobody will use CSV as an actual search index, but rather import it into something that performs this function better.
-
-In my personal use-case, I use SQLite. All other databases seem to have a good support for CSV imports.
 
 ## Development
 
@@ -70,14 +42,14 @@ gem build rdoc-markdown.gemspec
 gem install <path-to>/rdoc-markdown-0.1.2.gem
 ```
 
-or you can do the same, but through gemfile:
+or you can do the same through a Gemfile:
 
 ```
-gem 'rdoc-markdown`, path: "../rdoc-markdown/`
+gem 'rdoc-markdown', path: "../rdoc-markdown/"
 ```
 
 ## Testing
-Following command should run entire testsuit:
+The following command should run the entire test suite:
 ```
 rake test
 ```
@@ -88,72 +60,37 @@ To validate generated markdown against GitHub Flavored Markdown and check local
 rake markdown:validate
 ```
 
-This task validates:
-
-- generated sample docs,
-- checked-in `example/` docs,
-- generated `jekyll-seo-tag` docs,
-- vendored minitest docs,
-- vendored rails docs (Active Support, Active Record, Action Pack, Railties slices).
-
-Validation artifacts are written to `tmp/markdown-validate/` inside this repository.
-This task is also executed in CI.
-
 To lint markdown ERB templates:
 
 ```
 bundle exec rake erb:lint
 ```
 
-### Integration: minitest
-To run the integration harness against minitest (aligned with docs.seattlerb.org/minitest):
-
-```
-rake vendor:setup:minitest
-bundle exec rake test
-```
-
-The harness validates markdown formatting quality, generated page files, class/module paths, and search index output.
-
-### Integration: rails
-To run the rails harness (focused on Active Support + Active Record API docs with sdoc-like structure):
-
-```
-rake vendor:setup:rails
-bundle exec rake test
-```
-
-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:
 
+`./bin/generate.sh`
+
+or generate only some vendor docs:
+
 ```
-rake vendor:setup
 rake vendor:docs:jekyll_seo_tag
 rake vendor:docs:minitest
 rake vendor:docs:reverse_markdown
 rake vendor:docs:rails
-# or generate all
-rake vendor:docs
 ```
 
-`rake vendor:setup` also checks out the dependency-aligned `reverse_markdown` source in `vendor/reverse_markdown`.
-
-Output is written to:
+Find examples in the [/example](/example/) folder.
 
-- `vendor/docs/minitest`
-- `vendor/docs/jekyll-seo-tag`
-- `vendor/docs/reverse_markdown`
-- `vendor/docs/rails`
 
 ## Release
+
 ```
 gem build rdoc-markdown.gemspec
 gem push rdoc-markdown-0.1.2.gem
 ```
 
-There is `./bin/publish.sh` script that does that. But it assumes, that you have [gum library](https://github.com/charmbracelet/gum) installed.
+There is a `./bin/publish.sh` script that does that. However, it assumes that you have the [gum library](https://github.com/charmbracelet/gum) installed.
 
 ## Contributing
 
@@ -161,4 +98,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/skatko
 
 ## Code of Conduct
 
-Everyone interacting in the Rdoc::Markdown project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/skatkov/rdoc-markdown/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the RDoc::Markdown project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/skatkov/rdoc-markdown/blob/master/CODE_OF_CONDUCT.md).

data/lib/markdown.rb

@@ -1,7 +1,3 @@
 # frozen_string_literal: true
 
 require "rdoc/generator/markdown"
-
-# Compatibility namespace loaded by RDoc's generator discovery.
-class RDoc::Markdown
-end

data/lib/rdoc/discover.rb

@@ -1,7 +1 @@
-begin
-  require "markdown"
-rescue LoadError => error
-  puts error
-end
-
-puts "rdoc-markdown was discovered" if $DEBUG
+require "markdown"

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

@@ -0,0 +1,196 @@
+# 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)
+    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
+    anchor_aliases.each { |token, id| markdown.gsub!(token, %(<a id="#{id}"></a>)) }
+    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
+  end
+
+  class << self
+    private
+
+    # Normalizes HTML constructs that reverse_markdown cannot preserve directly.
+    #
+    # @param input [String] RDoc HTML fragment.
+    #
+    # @return [Nokogiri::HTML4::DocumentFragment] Normalized fragment.
+    def normalized_html_fragment(input)
+      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_link(heading, document)
+      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.inner_html = pre.text
+      end
+    end
+
+    # Normalizes one heading's leading fragment link.
+    #
+    # @param heading [Nokogiri::XML::Element] Heading element.
+    # @param document [Nokogiri::HTML4::Document] Owning document.
+    #
+    # @return [void]
+    def normalize_heading_link(heading, document)
+      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 [Array<Array<String>>] Token and anchor ID pairs.
+    def tokenize_legacy_anchors(anchors)
+      anchors.map.with_index do |span, index|
+        token = "RDocMarkdownAnchor#{index}End"
+        id = span["id"]
+        span.replace(token)
+        [token, id]
+      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.
+    #
+    # @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
+        body = Regexp.last_match(1)
+        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

@@ -2,11 +2,19 @@
 
 # Prevents RDoc from linking to code objects omitted from Markdown output.
 module RDoc::Generator::Markdown::CrossrefExtension
-  # Cross-reference resolver scoped to this formatter instance.
-  attr_writer :markdown_cross_reference
-
-  # Object IDs emitted by the active Markdown generator.
-  attr_writer :markdown_output_object_ids
+  # 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.
   #

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+# Renders RDoc descriptions and metadata for Markdown templates.
+module RDoc::Generator::Markdown::Descriptions
+  private
+
+  # 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)
+    cell = metadata_table_cell(label)
+    return cell unless RDoc::ClassModule === target
+
+    output_path = generation_state.class_output_paths[target.full_name]
+    return cell unless output_path
+
+    "[#{cell}](#{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(/[\\|]/) { |character| "\\#{character}" }
+  end
+
+  # Renders an RDoc description with links limited to emitted objects.
+  #
+  # @param code_object [RDoc::CodeObject, RDoc::Context::Section] Object whose description is rendered.
+  #
+  # @return [String] HTML description.
+  def render_description(code_object)
+    formatter = description_formatter(code_object)
+    formatter.extend(RDoc::Generator::Markdown::CrossrefExtension)
+    formatter.with_markdown_cross_references(
+      RDoc::CrossReference.new(formatter.context),
+      generation_state.markdown_output_object_ids
+    ) do
+      render_formatted_description(code_object, formatter, options.locale)
+    end
+  end
+
+  # Returns the formatter appropriate for an object or section.
+  #
+  # @param code_object [RDoc::CodeObject, RDoc::Context::Section] Described object.
+  #
+  # @return [RDoc::Markup::Formatter] Formatter configured for the object.
+  def description_formatter(code_object)
+    return code_object.formatter unless RDoc::Context::Section === code_object
+
+    code_object.parent.formatter.dup.tap { |copy| copy.code_object = code_object }
+  end
+
+  # Renders an object through its configured formatter.
+  #
+  # @param code_object [RDoc::CodeObject, RDoc::Context::Section] Described object.
+  # @param formatter [RDoc::Markup::Formatter] Formatter receiving parsed markup.
+  # @param locale [RDoc::I18n::Locale, nil] Translation locale.
+  #
+  # @return [String] Formatted HTML description.
+  def render_formatted_description(code_object, formatter, locale)
+    return code_object.description unless RDoc::Context::Section === code_object
+
+    documents = code_object.comments.map { |comment| localized_comment_document(comment, locale) }
+    RDoc::Markup::Document.new(*documents).accept(formatter)
+  end
+
+  # Parses one section comment, translating a copy when needed.
+  #
+  # @param comment [RDoc::Comment] Section comment.
+  # @param locale [RDoc::I18n::Locale, nil] Translation locale.
+  #
+  # @return [RDoc::Markup::Document] Parsed comment document.
+  def localized_comment_document(comment, locale)
+    return comment.parse unless locale && !comment.text.empty?
+
+    translated = comment.dup
+    translated.text = RDoc::I18n::Text.new(translated).translate(locale)
+    translated.parse
+  end
+
+  # Renders an RDoc object's description as Markdown.
+  #
+  # @param code_object [RDoc::CodeObject] Object with an RDoc description.
+  # @param fallback [String, nil] Text to use when the description is empty.
+  # @param heading_level_offset [Integer] Heading levels to add while rendering.
+  #
+  # @return [String] Rendered description or fallback text.
+  def describe(code_object, fallback: nil, heading_level_offset: 0)
+    description = render_description(code_object)
+    return fallback.to_s if description.empty?
+
+    RDoc::Generator::Markdown::Conversion.markdownify(description, heading_level_offset: heading_level_offset)
+  end
+
+  # Renders a section description as Markdown.
+  #
+  # @param section [RDoc::Context::Section] RDoc section whose description appears before grouped members.
+  # @param heading_level_offset [Integer] Heading levels to add while rendering.
+  #
+  # @return [String] Rendered section description.
+  def section_description(section, heading_level_offset:)
+    RDoc::Generator::Markdown::Conversion.markdownify(
+      render_description(section),
+      heading_level_offset: heading_level_offset
+    )
+  end
+
+  # Renders a method description or an alias fallback.
+  #
+  # @param method [RDoc::AnyMethod] Method object to render.
+  # @param current_class [RDoc::Context] Class or module currently being rendered.
+  # @param heading_level_offset [Integer] Heading levels to add while rendering.
+  #
+  # @return [String] Rendered method description.
+  def method_description(method, current_class:, heading_level_offset:)
+    text = describe(method, heading_level_offset: heading_level_offset)
+    return text unless text.empty?
+
+    aliased_method = method.is_alias_for
+    return "Not documented." unless aliased_method
+
+    alias_description(aliased_method, method_link(aliased_method, current_class: current_class))
+  end
+
+  # Formats an alias fallback with an optional target link.
+  #
+  # @param aliased_method [RDoc::AnyMethod] Alias target.
+  # @param link [String, nil] Generated link target.
+  #
+  # @return [String] Alias description.
+  def alias_description(aliased_method, link)
+    name = aliased_method.name
+    return "Alias for: `#{name}`" unless link
+
+    "Alias for: [`#{name}`](#{link})"
+  end
+
+  # Builds a Markdown link target for an aliased method.
+  #
+  # @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.
+  def method_link(method, current_class:)
+    return unless method.display?
+
+    target_parent = method.parent
+    target_path = generation_state.class_output_paths[target_parent.full_name]
+    return unless target_path
+
+    anchor = method.aref
+    return "##{anchor}" if target_parent == current_class
+
+    "#{target_path}##{anchor}"
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Writes the generated documentation search index.
+module RDoc::Generator::Markdown::Index
+  private
+
+  # Writes a CSV search index for generated documentation.
+  #
+  # @return [void]
+  def emit_csv_index
+    CSV.open("#{output_dir}/index.csv", "wb") { |csv| write_index(csv) }
+  end
+
+  # Writes all search-index rows.
+  #
+  # @param csv [CSV] Open CSV writer.
+  #
+  # @return [void]
+  def write_index(csv)
+    csv << %w[name type path]
+    classes.each { |klass| write_class_rows(csv, klass, output_path_for(klass)) }
+    pages.each { |page| csv << [File.basename(normalize_input_path_for_output(page.relative_name)), "File", page_output_path(page)] }
+  end
+
+  # Writes one class and its visible member rows.
+  #
+  # @param csv [CSV] Open CSV writer.
+  # @param klass [RDoc::Context] Class or module to index.
+  # @param output_path [String] Generated Markdown path.
+  #
+  # @return [void]
+  def write_class_rows(csv, klass, output_path)
+    class_name = klass.full_name
+    csv << [class_name, klass.type.capitalize, output_path]
+
+    klass.method_list.select(&:display?).each do |method|
+      csv << ["#{class_name}.#{method.name}", "Method", "#{output_path}##{method.aref}"]
+    end
+    klass.constants.select(&:display?).sort.each do |const|
+      name = const.name
+      csv << ["#{class_name}.#{name}", "Constant", "#{output_path}##{name}"]
+    end
+    klass.attributes.select(&:display?).sort.each do |attr|
+      csv << ["#{class_name}.#{attr.name}", "Attribute", "#{output_path}##{attr.aref}"]
+    end
+  end
+end