asciisourcerer 0.4.0 → 0.5.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,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

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

data/lib/sourcerer/source_skim/skimmer.rb

@@ -16,6 +16,23 @@ module Sourcerer
       # raw text (i.e., were not resolved by the parser).
       INCLUDE_DIRECTIVE_PATTERN = /include::[^\[]+\[[^\]]*\]/
 
+      # Matches a real (non-code-block) include directive at the start of a line,
+      # capturing the target path and its attribute list.
+      INCLUDE_LINE_PATTERN = /\A\s*include::([^\[]+)\[([^\]]*)\]\s*\z/
+
+      # Toggled by classic listing (----) / literal (....) block delimiters, so
+      # #detect_general_includes can skip include directives already captured
+      # (as literal example text) by the code_blocks/literal_blocks categories.
+      FENCE_DELIMITER_PATTERN = /\A(?:-{4,}|\.{4,})\s*\z/
+
+      # A document with a real title line can still end up with no `title`
+      # document attribute if a preceding, unresolved include directive
+      # disrupts Asciidoctor's header parsing (a known Asciidoctor quirk, not
+      # something this document did wrong). When that happens, Document#doctitle
+      # silently falls back to the first section's title. Detect that specific
+      # failure mode and recover the real title from the raw source instead.
+      RAW_TITLE_LINE_PATTERN = /\A=\s+(\S.*)\z/
+
       def process document, config: Config.new
         @config = config
         @main_file = document.attr('docfile')
@@ -36,7 +53,7 @@ module Sourcerer
         assign_line_ends(tree, doc_end)
 
         result = {
-          title: document.doctitle,
+          title: doctitle_for(document),
           lines: doc_end
         }
 
@@ -61,12 +78,88 @@ module Sourcerer
         result[:admonitions]      = @admonitions       if @config.include?(:admonitions)
         result[:quotes]           = @quotes            if @config.include?(:quotes)
         result[:images]           = @images            if @config.include?(:images)
+        result[:includes]         = detect_general_includes(document) if @config.include?(:includes)
 
         result
       end
 
       private
 
+      # Prefer Asciidoctor's own doctitle, but recover from the header-parsing
+      # failure mode described at RAW_TITLE_LINE_PATTERN: if the `title`
+      # attribute never got set (the real signal that header parsing broke,
+      # as opposed to a document that's genuinely untitled), look for an
+      # explicit `= Title` line in the raw source before trusting the
+      # first-section fallback.
+      def doctitle_for document
+        return document.doctitle if document.attr('title')
+
+        raw_title = raw_doctitle(document)
+        raw_title || document.doctitle
+      end
+
+      def raw_doctitle document
+        lines = document.source_lines
+        return nil unless lines
+
+        lines.each do |line|
+          return ::Regexp.last_match(1) if line =~ RAW_TITLE_LINE_PATTERN
+          # A section heading appearing before any `=` title line means the
+          # document genuinely has no title; stop looking.
+          break if line =~ /\A==+\s+\S/
+        end
+        nil
+      end
+
+      # Scan the raw source (outside of listing/literal delimited blocks, which
+      # are already covered by the code_blocks/literal_blocks `includes` field)
+      # for include directives, whether or not they were resolved by the parser.
+      def detect_general_includes document
+        lines = document.source_lines
+        return [] unless lines
+
+        offset   = source_line_offset(document)
+        includes = []
+        in_fence = false
+        lines.each_with_index do |line, idx|
+          if line =~ FENCE_DELIMITER_PATTERN
+            in_fence = !in_fence
+            next
+          end
+          next if in_fence
+
+          next unless (m = line.match(INCLUDE_LINE_PATTERN))
+
+          entry = { target: m[1].strip, starts_at: idx + 1 + offset }
+          entry.merge!(parse_include_attrs(m[2]))
+          includes << entry
+        end
+        includes
+      end
+
+      # document.source_lines reflects content *after* skip-front-matter
+      # stripping, while every other category's starts_at comes from
+      # Asciidoctor's own line-number tracking, which counts the stripped
+      # front matter lines too. Compute that offset so line numbers stay
+      # consistent across the whole skim.
+      def source_line_offset document
+        front_matter = document.attr('front-matter')
+        return 0 unless front_matter && !front_matter.empty?
+
+        front_matter.count("\n") + 1 + 2 # captured lines + both '---' delimiters
+      end
+
+      def parse_include_attrs attrs_str
+        attrs = {}
+        if (m = attrs_str.match(/\btags?=("[^"]*"|'[^']*'|\S+)/))
+          attrs[:tags] = m[1].delete('"\'')
+        end
+        if (m = attrs_str.match(/\bleveloffset=("[^"]*"|'[^']*'|\S+)/))
+          attrs[:leveloffset] = m[1].delete('"\'')
+        end
+        attrs
+      end
+
       def line_count_for file_path
         return nil unless file_path && File.exist?(file_path)
 

data/lib/sourcerer/source_skim.rb

@@ -6,6 +6,7 @@ require_relative 'yaml_frontmatter'
 require_relative 'source_skim/config'
 require_relative 'source_skim/skimmer'
 require_relative 'source_skim/markdown_skimmer'
+require_relative 'source_skim/ruby_skimmer'
 
 module Sourcerer
   # SourceSkim produces machine-oriented skims of markup source documents.
@@ -57,11 +58,15 @@ module Sourcerer
     # @param attributes [Hash{String => String}] AsciiDoc only. Asciidoctor
     #   attribute overrides. Silently ignored for Markdown.
     # @return [Hash] JSON-ready skim
-    def self.skim_file file_path, forms: nil, format: nil, categories: nil, attributes: {}
+    def self.skim_file file_path, forms: nil, format: nil, categories: nil, attributes: {}, descriptions: false
       fmt = format || detect_format(file_path)
       if fmt == :markdown
         config = Config.new(forms: forms || [:flat])
         MarkdownSkimmer.new.process(File.read(file_path), config: config)
+      elsif fmt == :ruby
+        RubySkimmer.new.process(
+          File.read(file_path),
+          config: Config.new(forms: forms || [:flat], descriptions: descriptions))
       else
         attrs = LOAD_OPTS[:attributes].merge(attributes)
         opts  = LOAD_OPTS.merge(attributes: attrs)
@@ -82,10 +87,12 @@ module Sourcerer
     # @param categories [Array<Symbol>, nil] AsciiDoc only
     # @param attributes [Hash{String => String}] AsciiDoc only
     # @return [Hash] JSON-ready skim
-    def self.skim_string content, format: :asciidoc, forms: nil, categories: nil, attributes: {}
+    def self.skim_string content, format: :asciidoc, forms: nil, categories: nil, attributes: {}, descriptions: false
       if format == :markdown
         config = Config.new(forms: forms || [:flat])
         MarkdownSkimmer.new.process(content, config: config)
+      elsif format == :ruby
+        RubySkimmer.new.process(content, config: Config.new(forms: forms || [:flat], descriptions: descriptions))
       else
         attrs = LOAD_OPTS[:attributes].merge(attributes)
         opts  = LOAD_OPTS.merge(attributes: attrs)
@@ -113,6 +120,8 @@ module Sourcerer
       ext = File.extname(file_path).downcase
       if Sourcerer::MARKDOWN_EXTS.include?(ext)
         :markdown
+      elsif ext == '.rb'
+        :ruby
       else
         :asciidoc
       end