asciisourcerer 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e85e0efc612880e0a0e62bef37b836015007d18074a74f890edc9db56791772c
-  data.tar.gz: 3fc912495515ae3b1a42016e3b5de6fd2a136533e53f981d42a14b5860a5038f
+  metadata.gz: 862206bd89bcd6930165344b8623239c8220f5d598f12d3050508b8386432546
+  data.tar.gz: 6b95b84ae0f56421fc10b75a440cf4beaa29c24d7c3f7be50f9c168b3e4b9a63
 SHA512:
-  metadata.gz: d2f3ed3a3b52950034965fa3edde7bf7159c7a907885e90b74e1a1e623b7996b9d7e4f03b72bf9f4cc7bfd8dc8cb7179deed2f38e8cf3adca04b5e34f0753bde
-  data.tar.gz: b859463483fb45eb5d84d326301b4c44adf2716f719cfdb77ecd4293d92dc23b3e9c8dc4128129ec84287d08d94761a250d9b629d451ac7b9fb77eddbbcbb08b
+  metadata.gz: a6ef512103f8978b1fe583a7e55061d94cade1f783cffb43bb68044d154a7c438f7a9e2a2e55a9a0ad499304881c30f375eb6b666f12e5d7d1ce56dc3401d49a
+  data.tar.gz: 6101084fa33316a51458b08878a17b956dbb93558fe7acdd6f95675167daa2d7f8ee29e76943123b18889a54780914a6cc95fcef0ee7aee628daf0d201b0f550

data/BILL_OF_MATERIALS.adoc

@@ -0,0 +1,17 @@
+= Bill of Materials
+:toc:
+
+This document lists third-party source code and documentation code copied (rather than referenced) in this repository, per license terms requiring attribution.
+
+[[shopify-liquid]]
+== Shopify Liquid
+
+[horizontal]
+Project::
+https://github.com/Shopify/liquid[Shopify/liquid]
+
+License::
+https://github.com/Shopify/liquid/blob/main/LICENSE[MIT], Copyright (C) 2005, 2006 Tobias Luetke
+
+Version::
+https://github.com/Shopify/liquid/blob/v5.13.0/lib/liquid/standardfilters.rb[`v5.13.0`]

data/README.adoc

@@ -37,11 +37,11 @@ endif::[]
 :this_prod_name: {this_proj_name}
 // end::universal-settings[]
 :this_prod_vrsn_major: 0
-:this_prod_vrsn_minor: 4
+:this_prod_vrsn_minor: 5
 :this_prod_vrsn_majmin: {this_prod_vrsn_major}.{this_prod_vrsn_minor}
 :this_prod_vrsn_patch: 0
 :this_prod_vrsn: {this_prod_vrsn_majmin}.{this_prod_vrsn_patch}
-:next_prod_vrsn: 0.5.0
+:next_prod_vrsn: 0.6.0
 // end::global-settings[]
 // end::ai-prompt[]
 :toc: macro
@@ -100,8 +100,10 @@ AsciiDoc-to-Markdown conversion::
 Convert AsciiDoc documents to Markdown for agentic consumption, with a focus on preserving semantic structure and document frontmatter.
 See <<markdowngrade>>.
 
-AsciiDoc and Markdown source inspection::
-Skim AsciiDoc documents to produce machine-oriented outlines of sections, code blocks, tables, and other semantic elements for tooling and agent consumption.
+AsciiDoc, Markdown, and Ruby source inspection::
+Skim source files to produce machine-oriented outlines.
+For AsciiDoc files, includes sections, code blocks, tables, and other semantic elements for tooling and agent consumption.
+For Ruby files, includes classes, modules, methods and their docstrings.
 See <<source-skim>>.
 
 General-purpose utilities::
@@ -219,7 +221,8 @@ For end-to-end AsciiDoc conversion, use `Sourcerer::AsciiDoc.mark_down_grade`, w
 
 Core behavior defaults::
 * Preserve section heading anchors.
-* Preserve semantic definition lists (`<dl>`, `<dt>`, `<dd>`).
+* Convert definition lists (`<dl>`, `<dt>`, `<dd>`) to Markdown by default (opt-out via `.no-markdown`).
+* Preserve HTML tables as-is by default (opt-in conversion via `.to-markdown`).
 * Preserve frontmatter when enabled.
 * Support semantic backend requests with fallback (`asciidoctor-html5s` -> `html5s` or `html5`).
 
@@ -259,6 +262,63 @@ markdown = Sourcerer::MarkDownGrade.convert_html(
 puts(markdown)
 ----
 
+[[markdowngrade-opt-in-conversion]]
+==== Conversion Controls: Tables and Definition Lists
+
+HTML tables are preserved as HTML by default; definition lists are *converted to Markdown by default*.
+Both support the same opt-in/opt-out class, frontmatter, and global-config mechanism.
+
+[[table-conversion]]
+===== Table conversion
+
+[cols="1,3",options="header"]
+|===
+| Control | Behavior
+| `.to-markdown` class on `<table>` or its `<div>` wrapper
+| Always convert this table to Markdown pipe syntax.
+| `.no-markdown` class on `<table>` or wrapper
+| Always keep this table as HTML (overrides global and frontmatter settings).
+| `tables-to-markdown: true` in YAML frontmatter
+| Convert all tables in the document unless `.no-markdown` overrides.
+| `convert_tables_to_markdown: true` in `bootstrap!` or `convert_html` options
+| Global default; overridden by frontmatter and per-table classes.
+|===
+
+.AsciiDoc example: per-table opt-in
+[source,asciidoc]
+----
+[.to-markdown]
+|===
+| Col A | Col B
+| value | value
+|===
+----
+
+[[dl-conversion]]
+===== Definition list (DL) conversion
+
+Definition lists (`<dl>/<dt>/<dd>`) are converted to Markdown by default.
+Rich content nested inside `<dd>` elements (lists, fenced code blocks, inline code) is recursively down-graded along with the parent term.
+Use `.no-markdown` to preserve a specific DL as HTML.
+
+When converted to Markdown, `<dt>` terms are rendered as `+*Term:*+`, and `<dd>` definitions are indented by three spaces.
+Block-level content inside `<dd>` (lists, fenced code blocks) is preserved within the indented block.
+
+[cols="1,3",options="header"]
+|===
+| Control | Behaviour
+| `.to-markdown` class on `<dl>` or its parent `<div>`
+| Force conversion to Markdown even when global mode is disabled.
+| `.no-markdown` class on `<dl>` or parent `<div>`
+| Keep this DL as HTML (overrides global and frontmatter settings).
+| `dls-to-markdown: false` in YAML frontmatter
+| Preserve all DLs in the document as HTML unless `.to-markdown` overrides.
+| `convert_dls_to_markdown: false` in `bootstrap!` or `convert_html` options
+| Disable conversion globally; overridden by frontmatter and per-DL classes.
+|===
+
+
+
 [[markdowngrade-migration]]
 ==== Migration Mini-Guide (DocOps Lab)
 
@@ -437,7 +497,7 @@ Schema-aware filters (including SGYML-specific classification filters) should be
 [[source-skim]]
 === SourceSkim
 
-`Sourcerer::SourceSkim` generates machine-oriented _skims_ of AsciiDoc and Markdown source documents.
+`Sourcerer::SourceSkim` generates machine-oriented _skims_ of AsciiDoc, Markdown, and Ruby source documents.
 
 A skim is a structured, JSON/YAML-ready outline of selected source elements.
 AsciiDoc skims include:
@@ -445,6 +505,8 @@ sections, code blocks, definition lists, tables, images, and more.
 
 Markdown skims include only sections and frontmatter, since other semantic elements are not reliably parseable in Markdown's freeform syntax.
 
+Ruby skims include classes, modules, and methods, along with their docstrings.
+
 Skims are intended to help tooling and agents inspect documentation source without ingesting full file contents.
 
 .Example: Skim a file for sections and code blocks
@@ -464,6 +526,9 @@ skim = Sourcerer::SourceSkim.skim_string(raw_adoc_content)
 
 # Skim Markdown file with flat sections only
 skim = Sourcerer::SourceSkim.skim_file('README.md', forms: [:flat])
+
+# Skim a Ruby file with docstrings
+skim = Sourcerer::SourceSkim.skim_file('lib/my_gem.rb', forms: [:tree], descriptions: true)
 ----
 
 Section shapes::
@@ -492,7 +557,6 @@ require 'asciidoctor/extensions/source-skim-tree-processor/extension'
 Asciidoctor::Extensions.register Sourcerer::SourceSkim::TreeProcessorExtension
 ----
 
-
 [[utilities]]
 === Utilities
 
@@ -755,6 +819,20 @@ Use `private_class_method` for singleton helper methods defined with `def self.*
 Use `private` for instance helper methods in classes or mixins.
 Avoid exporting helper methods as accidental public API.
 
+[[generated-docs]]
+=== Generated Reference Docs
+
+Some reference documentation is generated from data rather than hand-written, so it can't drift from what the code actually does.
+`specs/data/docs-manifest.yml` lists each generation job: a Liquid (or ERB) template, a YAML data source, an output path, and optional `vars` to parameterize a shared template into multiple outputs.
+
+For example, `specs/data/liquid-filters.yml` (the same source of truth used by the Liquid filter test suite; see <<tests>>) is rendered through `docs/templates/liquid-filters-ref.adoc.liquid` twice -- once grouped by filter category, once by filter source -- producing the partials committed at `lib/sourcerer/_docs/partials/liquid-filters-by-kind.adoc` and `liquid-filters-by-source.adoc`.
+These partials ship with the gem so downstream tools can `include::` them directly.
+
+Regenerate all manifest entries with:
+
+[.prompt]
+ bundle exec rake generate:docs
+
 [[tests]]
 === Tests
 
@@ -811,3 +889,5 @@ AsciiSourcerer does not yet publish a release history document.
 == Legal
 
 Sourcerer is licensed under the MIT License.
+
+A `BILL_OF_MATERIALS.adoc` file is available in the source repository and the gem package.