asciisourcerer 0.4.0 → 0.6.0

data/lib/sourcerer/mark_down_grade.rb

@@ -22,7 +22,8 @@ module Sourcerer
     @config = {
       preserve_heading_ids: true,
       strip_internal_links: false,
-      convert_tables_to_markdown: false
+      convert_tables_to_markdown: false,
+      convert_dls_to_markdown: true
     }
 
     class << self
@@ -34,6 +35,7 @@ module Sourcerer
     #   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)
 
@@ -47,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
@@ -138,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
 
@@ -426,6 +463,12 @@ module Sourcerer
     # 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 initialize
         super
@@ -433,6 +476,8 @@ module Sourcerer
       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)
@@ -464,6 +509,46 @@ module Sourcerer
 
       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
@@ -509,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
@@ -526,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
@@ -546,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
 
@@ -570,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
@@ -618,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
@@ -650,13 +747,16 @@ module Sourcerer
     # 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
 
-      # Determine effective table conversion mode
-      effective_mode = determine_table_conversion_mode(html.to_s, options)
-      Thread.current[:sourcerer_table_conversion_mode] = effective_mode
+      # 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)
@@ -664,14 +764,33 @@ module Sourcerer
         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)
 
-        markdown.gsub('<!--CHECKBOX_CHECKED-->', '- [x]')
-                .gsub('<!--CHECKBOX_UNCHECKED-->', '- [ ]')
+        # 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
+
+    # 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={}
       convert_html(html, options)
     end
@@ -773,6 +892,38 @@ module Sourcerer
       @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:
@@ -820,6 +971,8 @@ module Sourcerer
                          :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,10 @@ module Sourcerer
           render_entry[:out],
           data_object: data_obj,
           attrs_source: attrs_source,
-          engine: engine)
+          engine: engine,
+          vars: render_entry[:vars] || {},
+          preserve_missing: render_entry[:preserve_missing] || false,
+          preserve_empty: render_entry[:preserve_empty] || false)
       end
     end
 
@@ -49,37 +52,56 @@ 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).
+    # @param preserve_missing [Boolean] Liquid-only, independent of
+    #   `preserve_empty`. When true, a `{{ ... }}` expression that evaluates
+    #   to nil renders as its own original source text instead of an empty
+    #   string, so an unfilled field stays visible for manual completion
+    #   rather than silently disappearing. Has no effect on a defined
+    #   empty value (`""`, `[]`, `{}`).
+    # @param preserve_empty [Boolean] Liquid-only, independent of
+    #   `preserve_missing`. When true, a `{{ ... }}` expression that
+    #   evaluates to a defined-but-empty String/Array/Hash (`""`, `[]`,
+    #   `{}`) is preserved as its own original source text the same way.
+    #   Has no effect on nil. `0` and `false` are never affected by either
+    #   option.
     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
+                                 preserve_missing preserve_empty]
       unknown_option_keys = options.keys - supported_option_keys
       raise ArgumentError, "unknown option(s): #{unknown_option_keys.join(', ')}" unless unknown_option_keys.empty?
 
       data_object = options.fetch(:data_object, 'data')
-      includes_load_paths = options.fetch(:includes_load_paths, [])
-      attrs_source = options[:attrs_source]
-      engine = options.fetch(:engine, 'liquid')
+      data = load_render_data(data_file, options[:attrs_source])
+      vars = (options[:vars] || {}).transform_keys(&:to_s)
+      context = { data_object => data, 'include' => { data_object => data }, 'vars' => vars }
+
+      preserve = { missing: options.fetch(:preserve_missing, false), empty: options.fetch(:preserve_empty, false) }
+      rendered = render_in_engine(
+        options.fetch(:engine, 'liquid'), template_file, context, options.fetch(:includes_load_paths, []), preserve)
 
-      data = load_render_data(data_file, attrs_source)
       out_file = File.expand_path(out_file)
       FileUtils.mkdir_p(File.dirname(out_file))
-
-      template_path = File.expand_path(template_file)
-      template_content = File.read(template_path)
-
-      context = {
-        data_object => data,
-        'include' => { data_object => data }
-      }
-
-      rendered = case engine.to_s
-                 when 'erb' then render_erb(template_content, context)
-                 when 'liquid' then render_liquid(template_file, template_content, context, includes_load_paths)
-                 else raise ArgumentError, "Unsupported template engine: #{engine}"
-                 end
-
       File.write(out_file, rendered)
     end
 
+    # @api private
+    # Dispatches rendering to the requested template engine.
+    #
+    # @param preserve [Hash] `{missing:, empty:}` -- see {.render_template}'s
+    #   `preserve_missing`/`preserve_empty` options.
+    # @return [String]
+    def self.render_in_engine engine, template_file, context, includes_load_paths, preserve
+      template_content = File.read(File.expand_path(template_file))
+      case engine.to_s
+      when 'erb' then render_erb(template_content, context)
+      when 'liquid' then render_liquid(template_file, template_content, context, includes_load_paths, preserve)
+      else raise ArgumentError, "Unsupported template engine: #{engine}"
+      end
+    end
+
     # Renders output using a converter callable or converter constant name.
     #
     # @param render_entry [Hash] Render entry containing converter config.
@@ -145,38 +167,43 @@ module Sourcerer
     # @param template_content [String]
     # @param context [Hash]
     # @param includes_load_paths [Array<String>]
+    # @param preserve [Hash] `{missing:, empty:}` -- see {.render_template}'s
+    #   `preserve_missing`/`preserve_empty` options.
     # @return [String]
-    def self.render_liquid template_file, template_content, context, includes_load_paths
+    def self.render_liquid template_file, template_content, context, includes_load_paths, preserve
       require_relative 'jekyll'
       require_relative 'jekyll/liquid/filters'
       require_relative 'jekyll/liquid/tags'
+      require_relative 'jekyll/liquid/preserve_missing_variables'
       require 'liquid' unless defined?(Liquid::Template)
       Sourcerer::Jekyll.initialize_liquid_runtime
 
+      registers = liquid_registers(template_file, includes_load_paths)
+      template = Liquid::Template.parse(template_content)
+      render = -> { template.render(context, registers: registers) }
+
+      return render.call unless preserve[:missing] || preserve[:empty]
+
+      Sourcerer::Jekyll::Liquid::PreserveMissingVariables.with_active(
+        preserve_missing: preserve[:missing], preserve_empty: preserve[:empty], &render)
+    end
+
+    # @api private
+    # Builds the Liquid registers hash (fake site + file system) a template
+    # render needs to resolve `{% embed %}`/include partials.
+    #
+    # @return [Hash]
+    def self.liquid_registers template_file, includes_load_paths
       fallback_templates_dir = File.expand_path('.', Dir.pwd)
       template_dir = File.dirname(File.expand_path(template_file))
       template_parent_dir = File.dirname(template_dir)
 
-      paths = if includes_load_paths.any?
-                includes_load_paths
-              else
-                [template_parent_dir, template_dir, fallback_templates_dir]
-              end
-
-      site = Sourcerer::Jekyll::Bootstrapper.fake_site(
-        includes_load_paths: paths,
-        plugin_dirs: [])
-
+      default_paths = [template_parent_dir, template_dir, fallback_templates_dir]
+      paths = includes_load_paths.any? ? includes_load_paths : default_paths
+      site = Sourcerer::Jekyll::Bootstrapper.fake_site(includes_load_paths: paths, plugin_dirs: [])
       file_system = Sourcerer::Jekyll::Liquid::FileSystem.new(paths)
 
-      template = Liquid::Template.parse(template_content)
-      options = {
-        registers: {
-          site: site,
-          file_system: file_system
-        }
-      }
-      template.render(context, options)
+      { site: site, file_system: file_system, includes_load_paths: paths }
     end
 
     # Render a Liquid template string directly with a data hash.
@@ -210,6 +237,8 @@ module Sourcerer
     private_class_method :load_render_data,
                          :resolve_converter,
                          :render_erb,
-                         :render_liquid
+                         :render_liquid,
+                         :render_in_engine,
+                         :liquid_registers
   end
 end

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