asciisourcerer 0.3.1 → 0.5.0

data/lib/sourcerer/mark_down_grade.rb

@@ -21,7 +21,9 @@ module Sourcerer
 
     @config = {
       preserve_heading_ids: true,
-      strip_internal_links: false
+      strip_internal_links: false,
+      convert_tables_to_markdown: false,
+      convert_dls_to_markdown: true
     }
 
     class << self
@@ -32,6 +34,8 @@ module Sourcerer
     # Options:
     #   preserve_heading_ids: (default: true) Include <a id="..."> anchors before headings
     #   strip_internal_links: (default: false) Remove href from internal anchor links, keeping only text
+    #   convert_tables_to_markdown: (default: false) Convert all tables to markdown UNLESS they have .no-markdown class
+    #   convert_dls_to_markdown: (default: true) Convert all DLs to markdown UNLESS they have .no-markdown class
     def self.bootstrap! options={}
       @config.merge!(options)
 
@@ -45,6 +49,7 @@ module Sourcerer
       register_blockquote_converter
       register_comment_converter
       register_link_converter
+      register_list_converters
     end
 
     # Enhanced Pre converter to handle additional code block language patterns
@@ -136,33 +141,67 @@ module Sourcerer
       end
     end
 
-    # Definition list converter: preserve semantic list tags in output.
-    class DlConverter < ReverseMarkdown::Converters::Base
+    # Definition list passthrough/converter: converts DL blocks to Markdown by default.
+    # DL blocks with .to-markdown class (or a parent div with that class) are converted to Markdown.
+    # Supports global conversion via convert_dls_to_markdown config or dls-to-markdown frontmatter key.
+    # Per-node .to-markdown and .no-markdown classes override the global mode.
+    # In AsciiDoc html5 output, [.to-markdown] on a dlist places the class on the outer <div>.
+    class DlPassthrough < ReverseMarkdown::Converters::Base
       def convert node, state={}
-        body = node.children.map { |child| treat(child, state) }.join.strip
-        attrs = []
-        attrs << %( class="#{node['class']}") if node['class']
-        attrs << %( role="#{node['role']}") if node['role']
-        "<dl#{attrs.join}>\n#{body}\n</dl>\n"
+        global_mode = Thread.current[:sourcerer_dl_conversion_mode] || false
+
+        has_to_markdown = check_class_on_node(node, 'to-markdown')
+        has_no_markdown = check_class_on_node(node, 'no-markdown')
+
+        # Also check parent <div> wrapper (html5 backend wraps dl in <div class="dlist ...">)
+        parent = node.parent
+        if parent && parent.name == 'div'
+          has_to_markdown ||= check_class_on_node(parent, 'to-markdown')
+          has_no_markdown ||= check_class_on_node(parent, 'no-markdown')
+        end
+
+        should_convert = if has_no_markdown
+                           false
+                         elsif has_to_markdown
+                           true
+                         else
+                           global_mode
+                         end
+
+        if should_convert
+          body = node.children.map { |child| treat(child, state) }.join.strip
+          "#{body}\n"
+        else
+          "#{node.to_html}\n"
+        end
+      end
+
+      private
+
+      def check_class_on_node node, class_name
+        node['class'].to_s.split.include?(class_name)
       end
     end
 
-    # Definition term converter: preserves <dt> with classes, converts content.
+    # Definition term converter: formats term as italicized with colon.
     class DtConverter < ReverseMarkdown::Converters::Base
       def convert node, state={}
-        class_attr = node['class'] ? %( class="#{node['class']}") : ''
-        "<dt#{class_attr}>#{treat_children(node, state)}</dt>\n"
+        term_text = treat_children(node, state).strip
+        "**#{term_text}:**\n"
       end
     end
 
-    # Definition description converter: preserves <dd>, converts nested content.
+    # Definition description converter: indents definition content by 3 spaces for Markdown.
+    # Block-level elements (lists, code blocks, etc.) within a definition are indented as-is,
+    # preserving their internal structure while still visually nesting under the term.
     class DdConverter < ReverseMarkdown::Converters::Base
       def convert node, state={}
-        content = treat_children(node, state)
-        attrs = []
-        attrs << %( class="#{node['class']}") if node['class']
-        attrs << %( role="#{node['role']}") if node['role']
-        "<dd#{attrs.join}>\n#{content.strip}\n</dd>\n"
+        content = treat_children(node, state).strip
+        # Indent non-blank lines of the definition by 3 spaces (works for both inline and
+        # block content); blank lines are left empty so they stay collapsible as paragraph
+        # breaks instead of becoming whitespace-only lines that pile up under nesting.
+        indented = content.split("\n").map { |line| line.strip.empty? ? '' : "   #{line}" }.join("\n")
+        "#{indented}\n\n"
       end
     end
 
@@ -421,9 +460,97 @@ module Sourcerer
     end
 
     # Passthrough Tables: preserve HTML tables as-is (except admonition internals handled elsewhere).
+    # Tables with "to-markdown" class are converted via ReverseMarkdown instead.
+    # Supports both html5 (class on <table>) and html5s (class on parent <div class="table-block">).
+    # Per-table classes (.to-markdown, .no-markdown) override the global conversion mode.
+    #
+    # Horizontal dlists ([horizontal]) render as a classless <table> inside a
+    # <div class="hdlist">, not as a <dl>, so they're intercepted here rather than
+    # by DlPassthrough. They follow the DL conversion mode/overrides (not the table
+    # mode), converting each hdlist1/hdlist2 row to "**Term:** Description" instead
+    # of a Markdown table.
     class TablePassthrough < ReverseMarkdown::Converters::Base
-      def convert node, _state={}
-        "#{node.to_html}\n"
+      def initialize
+        super
+        @markdown_converter = ReverseMarkdown::Converters::Table.new
+      end
+
+      def convert node, state={}
+        return convert_hdlist(node, state) if hdlist_table?(node)
+
+        global_mode = Thread.current[:sourcerer_table_conversion_mode] || false
+
+        # Check for per-table classes (on table or parent wrapper)
+        has_to_markdown = check_class_on_node(node, 'to-markdown')
+        has_no_markdown = check_class_on_node(node, 'no-markdown')
+
+        # Also check parent <div class="table-block"> wrapper (html5s backend)
+        parent_div = node.parent
+        if parent_div && parent_div.name == 'div'
+          has_to_markdown ||= check_class_on_node(parent_div, 'to-markdown')
+          has_no_markdown ||= check_class_on_node(parent_div, 'no-markdown')
+        end
+
+        # Determine whether to convert (per-table classes override global mode)
+        should_convert = if has_no_markdown
+                           false # .no-markdown always prevents conversion
+                         elsif has_to_markdown
+                           true  # .to-markdown always forces conversion
+                         else
+                           global_mode # Use global table conversion mode
+                         end
+
+        if should_convert
+          @markdown_converter.convert(node, state)
+        else
+          "#{node.to_html}\n"
+        end
+      end
+
+      private
+
+      def hdlist_table? node
+        parent = node.parent
+        parent && parent.name == 'div' && check_class_on_node(parent, 'hdlist')
+      end
+
+      def convert_hdlist node, state={}
+        global_mode = Thread.current[:sourcerer_dl_conversion_mode] || false
+
+        has_to_markdown = check_class_on_node(node, 'to-markdown')
+        has_no_markdown = check_class_on_node(node, 'no-markdown')
+
+        parent = node.parent
+        if parent && parent.name == 'div'
+          has_to_markdown ||= check_class_on_node(parent, 'to-markdown')
+          has_no_markdown ||= check_class_on_node(parent, 'no-markdown')
+        end
+
+        should_convert = if has_no_markdown
+                           false
+                         elsif has_to_markdown
+                           true
+                         else
+                           global_mode
+                         end
+
+        return "#{node.to_html}\n" unless should_convert
+
+        body = node.css('> tr').map { |row| convert_hdlist_row(row, state) }.join
+        "#{body}\n"
+      end
+
+      def convert_hdlist_row row, state={}
+        # Match by column position, not the hdlist1/hdlist2 classes: normalize_html_for_markdown
+        # (clean_html5s_tables!) strips class attributes from td/tr before this converter runs.
+        term_node, desc_node = row.css('> td')
+        term = term_node ? treat_children(term_node, state).strip : ''
+        desc = desc_node ? treat_children(desc_node, state).strip : ''
+        "**#{term}:** #{desc}\n"
+      end
+
+      def check_class_on_node node, class_name
+        node['class'].to_s.split.include?(class_name)
       end
     end
 
@@ -467,7 +594,7 @@ module Sourcerer
                    is_checked = checkbox['checked'] || checkbox['data-item-complete'] == '1'
                    # Remove the checkbox from the DOM so it doesn't get rendered again
                    checkbox.remove
-                   is_checked ? '<!--CHECKBOX_CHECKED--> ' : '<!--CHECKBOX_UNCHECKED--> '
+                   is_checked ? '- <!--CHECKBOX_CHECKED--> ' : '- <!--CHECKBOX_UNCHECKED--> '
                  else
                    prefix_for(node)
                  end
@@ -484,9 +611,11 @@ module Sourcerer
         result = "#{indentation}#{prefix}#{content}\n"
 
         nested_lists.each do |nested_list|
-          nested_state = state.merge(ol_count: state.fetch(:ol_count, 0) + 1)
-          nested_md = treat(nested_list, nested_state).strip
-          result << "#{nested_md}\n" unless nested_md.empty?
+          # Pass the same state; the Ul/Ol converter will handle ol_count incrementing.
+          # Use sub to strip only the leading newline emitted by the Ul/Ol converter,
+          # preserving per-line indentation built by indentation_from.
+          nested_md = treat(nested_list, state).sub(/\A\n+/, '').rstrip
+          result << "#{nested_md}\n" unless nested_md.strip.empty?
         end
 
         result
@@ -504,8 +633,11 @@ module Sourcerer
       end
 
       def indentation_from state
+        # Mirror ReverseMarkdown's built-in Li behaviour: ol_count is incremented by the
+        # Ul/Ol converter before reaching LI, so subtract 1 to get the nesting depth.
+        # ol_count 1 = top level (no indent), 2 = nested once (2 spaces), etc.
         length = state.fetch(:ol_count, 0)
-        '   ' * [length - 1, 0].max
+        '  ' * [length - 1, 0].max
       end
     end # class LiWithNestedLists
 
@@ -528,8 +660,10 @@ module Sourcerer
     end
 
     # Register all definition list converters.
+    # DlPassthrough handles opt-in conversion; DtConverter and DdConverter are
+    # called only when DlPassthrough decides to convert a given <dl>.
     def self.register_dl_converters
-      ReverseMarkdown::Converters.register :dl, DlConverter.new
+      ReverseMarkdown::Converters.register :dl, DlPassthrough.new
       ReverseMarkdown::Converters.register :dt, DtConverter.new
       ReverseMarkdown::Converters.register :dd, DdConverter.new
     end
@@ -576,6 +710,11 @@ module Sourcerer
       ReverseMarkdown::Converters.register :a, LinkConverter.new
     end
 
+    # Register list item converter to handle nested lists and checkboxes.
+    def self.register_list_converters
+      ReverseMarkdown::Converters.register :li, LiWithNestedLists.new
+    end
+
     # Normalize block titles so escaped inline emphasis from html5s is converted
     # to markdown emphasis consistently with html5 conversions.
     def self.normalize_block_title text
@@ -606,18 +745,50 @@ module Sourcerer
     end
 
     # Convert HTML into Markdown with MarkDownGrade converters.
+    # Options include:
+    #   convert_tables_to_markdown: Override global config for table conversion (true/false)
+    #   convert_dls_to_markdown: Override global config for DL conversion (true/false)
     def self.convert_html html, options={}
       bootstrap! unless @setup_complete
       @setup_complete = true
 
-      normalized_html = normalize_html_for_markdown(html.to_s)
-      markdown = ReverseMarkdown.convert(normalized_html, options)
-      markdown = markdown.gsub(/(\*\*[^\n]+\*\*  \n)\n+(?=\S)/, '\\1')
-      markdown = markdown.gsub(/<figcaption>\s+/, '<figcaption>')
-      markdown = markdown.gsub(%r{\s+</figcaption>}, '</figcaption>')
+      # Determine effective table and DL conversion modes
+      effective_table_mode = determine_table_conversion_mode(html.to_s, options)
+      effective_dl_mode = determine_dl_conversion_mode(html.to_s, options)
+      Thread.current[:sourcerer_table_conversion_mode] = effective_table_mode
+      Thread.current[:sourcerer_dl_conversion_mode] = effective_dl_mode
+
+      begin
+        normalized_html = normalize_html_for_markdown(html.to_s)
+        markdown = ReverseMarkdown.convert(normalized_html, options)
+        markdown = markdown.gsub(/(\*\*[^\n]+\*\*  \n)\n+(?=\S)/, '\\1')
+        markdown = markdown.gsub(/<figcaption>\s+/, '<figcaption>')
+        markdown = markdown.gsub(%r{\s+</figcaption>}, '</figcaption>')
+        markdown = normalize_blank_lines(markdown)
+
+        # Replace checkbox markers: handle indented list items and maintain correct dash placement
+        replace_checkbox_markers(markdown)
+      ensure
+        Thread.current[:sourcerer_table_conversion_mode] = nil
+        Thread.current[:sourcerer_dl_conversion_mode] = nil
+      end
+    end
+
+    # Collapse whitespace-only lines to truly blank ones, then collapse runs of
+    # 3+ consecutive newlines down to a single blank line (one \n\n). Nested
+    # definition lists and example blocks otherwise stack indentation and blank
+    # lines from each conversion level, producing long runs of whitespace-only lines.
+    def self.normalize_blank_lines markdown
+      markdown.gsub(/^[ \t]+$/, '').gsub(/\n{3,}/, "\n\n")
+    end
 
-      markdown.gsub('<!--CHECKBOX_CHECKED-->', '- [x]')
-              .gsub('<!--CHECKBOX_UNCHECKED-->', '- [ ]')
+    # Replace checkbox placeholder markers with proper Markdown checkbox syntax.
+    # Handles various indentation levels and ensures correct list item formatting.
+    def self.replace_checkbox_markers markdown
+      # Replace checkbox markers that appear after list item dashes
+      # Pattern: optional indentation + dash + space + marker + space
+      markdown.gsub(/^(\s*- )<!--CHECKBOX_CHECKED-->\s/, '\1[x] ')
+              .gsub(/^(\s*- )<!--CHECKBOX_UNCHECKED-->\s/, '\1[ ] ')
     end
 
     def self.convert html, options={}
@@ -629,6 +800,7 @@ module Sourcerer
       fragment = Nokogiri::HTML::DocumentFragment.parse(html_body)
       normalize_abstract_nodes!(fragment)
       normalize_footnote_nodes!(fragment)
+      clean_html5s_tables!(fragment)
       fragment.to_html
     end
 
@@ -682,10 +854,126 @@ module Sourcerer
       raw_id.empty? ? nil : raw_id
     end
 
+    # Clean HTML5s table artifacts: remove colgroup elements and class/style attributes from cells.
+    # This normalizes tables generated by the asciidoctor-html5s backend for safer Markdown conversion.
+    #
+    # @param fragment [Nokogiri::HTML::DocumentFragment] The HTML fragment to clean.
+    # @return [void] Modifies fragment in place.
+    def self.clean_html5s_tables! fragment
+      # Remove all colgroup elements
+      fragment.css('colgroup').each(&:remove)
+
+      # Remove class and style attributes from table cells and rows
+      fragment.css('td, th, tr').each do |cell|
+        cell.delete('class')
+        cell.delete('style')
+      end
+    end
+
+    # Determine the effective table conversion mode from options, frontmatter, or global config.
+    #
+    # Precedence:
+    # 1. Explicit convert_tables_to_markdown option in parameters
+    # 2. Document-level setting from frontmatter (YAML) or page attributes (AsciiDoc)
+    # 3. Global config setting
+    #
+    # @param html_body [String] The HTML document body.
+    # @param options [Hash] Optional override.
+    # @return [Boolean] Whether tables should be converted to markdown by default.
+    def self.determine_table_conversion_mode html_body, options
+      # Explicit option takes precedence
+      return options[:convert_tables_to_markdown] if options.key?(:convert_tables_to_markdown)
+
+      # Extract from document metadata
+      document_mode = extract_table_conversion_mode_from_html(html_body)
+      return document_mode unless document_mode.nil?
+
+      # Fall back to global config
+      @config[:convert_tables_to_markdown]
+    end
+
+    # Determine the effective DL conversion mode from options, frontmatter, or global config.
+    #
+    # Precedence:
+    # 1. Explicit convert_dls_to_markdown option in parameters
+    # 2. Document-level setting from frontmatter key: dls-to-markdown
+    # 3. Global config setting
+    #
+    # @param html_body [String] The HTML document body.
+    # @param options [Hash] Optional override.
+    # @return [Boolean] Whether DLs should be converted to markdown by default.
+    def self.determine_dl_conversion_mode html_body, options
+      return options[:convert_dls_to_markdown] if options.key?(:convert_dls_to_markdown)
+
+      document_mode = extract_dl_conversion_mode_from_html(html_body)
+      return document_mode unless document_mode.nil?
+
+      @config[:convert_dls_to_markdown]
+    end
+
+    # Extract DL conversion mode from document frontmatter.
+    #
+    # Checks for YAML frontmatter key: dls-to-markdown
+    #
+    # @param html_body [String] The HTML document body.
+    # @return [Boolean, nil] The setting if found, nil otherwise.
+    def self.extract_dl_conversion_mode_from_html html_body
+      frontmatter = Sourcerer::YamlFrontmatter.extract(html_body)
+      return string_to_boolean(frontmatter['dls-to-markdown']) if frontmatter.key?('dls-to-markdown')
+
+      nil
+    end
+
+    # Extract table conversion mode from document frontmatter or page attributes.
+    #
+    # Checks for:
+    # - YAML frontmatter key: tables-to-markdown
+    # - AsciiDoc page attribute: page-tables-to-markdown
+    #
+    # @param html_body [String] The HTML document body.
+    # @return [Boolean, nil] The setting if found, nil otherwise.
+    def self.extract_table_conversion_mode_from_html html_body
+      # Try to extract YAML frontmatter
+      frontmatter = Sourcerer::YamlFrontmatter.extract(html_body)
+      return string_to_boolean(frontmatter['tables-to-markdown']) if frontmatter.key?('tables-to-markdown')
+
+      # Try to find page-tables-to-markdown in HTML comments or metadata
+      # (This would be set by AsciiDoc's page attributes)
+      if html_body.include?('page-tables-to-markdown')
+        # Look for data attributes or comments that might encode this
+        if html_body.match?(/page-tables-to-markdown['"]?\s*[:=]\s*['"]*true/i)
+          return true
+        elsif html_body.match?(/page-tables-to-markdown['"]?\s*[:=]\s*['"]*false/i)
+          return false
+        end
+      end
+
+      nil
+    end
+
+    # Convert a string representation to a boolean value.
+    #
+    # @param value [String, Boolean, nil] The value to convert.
+    # @return [Boolean, nil] Boolean if value is truthy string, nil if unclear.
+    def self.string_to_boolean value
+      case value.to_s.downcase.strip
+      when 'true', '1', 'yes', 'on'
+        true
+      when 'false', '0', 'no', 'off', ''
+        false
+      end
+    end
+
     private_class_method :normalize_html_for_markdown,
                          :normalize_abstract_nodes!,
                          :normalize_footnote_nodes!,
-                         :canonical_footnote_anchor_id
+                         :canonical_footnote_anchor_id,
+                         :clean_html5s_tables!,
+                         :determine_table_conversion_mode,
+                         :extract_table_conversion_mode_from_html,
+                         :determine_dl_conversion_mode,
+                         :extract_dl_conversion_mode_from_html,
+                         :string_to_boolean
   end # module MarkDownGrade
 end # module Sourcerer
 

data/lib/sourcerer/rendering.rb

@@ -36,7 +36,8 @@ module Sourcerer
           render_entry[:out],
           data_object: data_obj,
           attrs_source: attrs_source,
-          engine: engine)
+          engine: engine,
+          vars: render_entry[:vars] || {})
       end
     end
 
@@ -49,8 +50,11 @@ module Sourcerer
     # @param includes_load_paths [Array<String>] Paths for Liquid includes.
     # @param attrs_source [String] The path to an AsciiDoc file for attributes.
     # @param engine [String] The template engine to use.
+    # @param vars [Hash] Arbitrary caller-supplied variables, exposed to the
+    #   template as `vars` (e.g. to parameterize a shared template between
+    #   multiple render entries in a manifest).
     def self.render_template template_file, data_file, out_file, **options
-      supported_option_keys = %i[data_object includes_load_paths attrs_source engine]
+      supported_option_keys = %i[data_object includes_load_paths attrs_source engine vars]
       unknown_option_keys = options.keys - supported_option_keys
       raise ArgumentError, "unknown option(s): #{unknown_option_keys.join(', ')}" unless unknown_option_keys.empty?
 
@@ -58,6 +62,7 @@ module Sourcerer
       includes_load_paths = options.fetch(:includes_load_paths, [])
       attrs_source = options[:attrs_source]
       engine = options.fetch(:engine, 'liquid')
+      vars = (options[:vars] || {}).transform_keys(&:to_s)
 
       data = load_render_data(data_file, attrs_source)
       out_file = File.expand_path(out_file)
@@ -68,7 +73,8 @@ module Sourcerer
 
       context = {
         data_object => data,
-        'include' => { data_object => data }
+        'include' => { data_object => data },
+        'vars' => vars
       }
 
       rendered = case engine.to_s
@@ -86,7 +92,7 @@ module Sourcerer
     # @return [void]
     def self.render_with_converter render_entry
       data_file = render_entry[:data]
-      out_file = render_entry[:out]
+      out_file  = render_entry[:out]
       raise ArgumentError, 'render entry missing :data' unless data_file
       raise ArgumentError, 'render entry missing :out' unless out_file
 

data/lib/sourcerer/source_skim/config.rb

@@ -16,6 +16,7 @@ module Sourcerer
       admonitions
       quotes
       images
+      includes
     ].freeze
 
     # Categories included when a caller passes +categories: nil+ (the default).
@@ -30,11 +31,12 @@ module Sourcerer
     # arguments on {Sourcerer::SourceSkim.skim_file} and friends.
     # @api private
     class Config
-      attr_reader :forms, :categories
+      attr_reader :forms, :categories, :descriptions
 
-      def initialize forms: [:tree], categories: nil
+      def initialize forms: [:tree], categories: nil, descriptions: false
         @forms = Array(forms).map(&:to_sym)
         @categories = categories ? Array(categories).map(&:to_sym) : DEFAULT_CATEGORIES.dup
+        @descriptions = descriptions
       end
 
       def include? category
@@ -48,6 +50,10 @@ module Sourcerer
       def flat?
         @forms.include?(:flat)
       end
+
+      def descriptions?
+        @descriptions
+      end
     end
   end
 end

data/lib/sourcerer/source_skim/ruby_skimmer.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'yard'
+
+module Sourcerer
+  module SourceSkim
+    # Parses Ruby source code and produces a JSON-ready skim hash.
+    #
+    # A new instance should be created per-document call. External callers should
+    # use {Sourcerer::SourceSkim.skim_file} or {Sourcerer::SourceSkim.skim_string}
+    # with a Ruby file or +format: :ruby+ rather than instantiating this class
+    # directly.
+    # @api private
+    class RubySkimmer
+      # @param content [String] raw Ruby source code
+      # @param config [Config]
+      # @return [Hash] JSON-ready skim
+      def process content, config: Config.new(forms: [:flat], descriptions: true)
+        require 'tempfile'
+
+        @config = config
+
+        # Set logging level to ERROR to suppress YARD warnings about missing files or other issues. This ensures that the skimming process is not interrupted by non-critical warnings.
+        YARD::Logger.instance.level = 3
+
+        # YARD's registry is a process-wide global. Without clearing it first,
+        # a class/module/method path already registered from a previous
+        # #process call keeps pointing at that call's (now-deleted) tempfile,
+        # so it would be silently excluded from every subsequent skim.
+        YARD::Registry.clear
+
+        # YARD's parser is designed for documentation generation, so it expects
+        # a file path to determine the source type.
+        Tempfile.create(['sourcerer', '.rb']) do |tempfile|
+          tempfile.write(content)
+          tempfile.flush
+
+          # Parse ONLY the modules, methods, and classes defined in the current file.
+          YARD::Parser::SourceParser.parse(tempfile.path)
+          objects = YARD::Registry.all(:class, :module, :method).select { |obj| obj.file == tempfile.path }
+
+          result = {}
+          result[:classes] = build_classes(objects.select { |obj| obj.type == :class })
+          result[:modules] = build_modules(objects.select { |obj| obj.type == :module })
+          result[:methods] = build_methods(objects.select { |obj| obj.type == :method })
+          result
+        end
+      end
+
+      private
+
+      def build_classes classes
+        classes.map do |cls|
+          {
+            name: cls.path,
+            line: cls.line
+          }.merge(
+            @config.descriptions? ? { desc: cls.docstring.to_s } : {})
+        end
+      end
+
+      def build_modules modules
+        modules.map do |mod|
+          {
+            name: mod.path,
+            line: mod.line
+          }.merge(
+            @config.descriptions? ? { desc: mod.docstring.to_s } : {})
+        end
+      end
+
+      def build_methods methods
+        methods.map do |meth|
+          {
+            name: meth.path,
+            line: meth.line
+          }.merge(
+            @config.descriptions? ? { desc: meth.docstring.to_s } : {})
+        end
+      end
+    end
+  end
+end