asciisourcerer 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c7773a8343dbad45adce3b1c32d959ed8e8da23afb1779e308999801eb32404
-  data.tar.gz: a9ff1c4838338f0302e9dbb202092309254be9c73dfe245f6ea61594a38e966e
+  metadata.gz: 862206bd89bcd6930165344b8623239c8220f5d598f12d3050508b8386432546
+  data.tar.gz: 6b95b84ae0f56421fc10b75a440cf4beaa29c24d7c3f7be50f9c168b3e4b9a63
 SHA512:
-  metadata.gz: e49749d692bd70ce7196fb54312e016b0daf5074d3949c49a4586e3c7f3da7e85d9e3c9b0d50013c3d8c8e8a14a9353323cd0f195cda0255956657aee42bf441
-  data.tar.gz: 9d10b6d87d315d5d5d254103cc82a3491b43f11fb784da16dc0516ee4697373e5b45d75a2aec29b4bab90d70e74d32f48ee5194108d576b5e7f4cd4f206506f9
+  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,12 +37,13 @@ endif::[]
 :this_prod_name: {this_proj_name}
 // end::universal-settings[]
 :this_prod_vrsn_major: 0
-:this_prod_vrsn_minor: 3
+:this_prod_vrsn_minor: 5
 :this_prod_vrsn_majmin: {this_prod_vrsn_major}.{this_prod_vrsn_minor}
-:this_prod_vrsn_patch: 1
+:this_prod_vrsn_patch: 0
 :this_prod_vrsn: {this_prod_vrsn_majmin}.{this_prod_vrsn_patch}
-:next_prod_vrsn: 0.4.0
+:next_prod_vrsn: 0.6.0
 // end::global-settings[]
+// end::ai-prompt[]
 :toc: macro
 :toclevels: 4
 :this_prod_repo_files_path: {this_proj_src_www_url}/tree/main
@@ -89,7 +90,7 @@ Initialize a Jekyll-routed Liquid runtime with DocOps Lab filters and tags, so J
 See <<templating-liquid-runtime>>.
 
 Build-time generation::
-Generate prebuild artifacts (attributes, snippets, regions) for downstream builds and runtime access.
+Generate pre-build artifacts (attributes, snippets, regions) for downstream builds and runtime access.
 See <<pipelines>>.
 
 AsciiDoc-to-manpage conversion::
@@ -99,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::
@@ -144,7 +147,7 @@ The most common workflows are summarized below.
 Basic render flow::
 Load YAML data, optionally enrich it with AsciiDoc attributes, render a template, and write output to a file.
 
-Prebuild flow::
+Pre-build flow::
 Extract attributes and tagged content from AsciiDoc into artifacts that are loaded at runtime.
 
 Converter flow::
@@ -218,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`).
 
@@ -258,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)
 
@@ -329,7 +390,7 @@ NOTE: Only blocks marked `_skip` are not carried over.
 sync::
 Ongoing operation that scans for canonical blocks, replaces their content with the prime version (after optional Liquid rendering), and leaves everything else verbatim.
 
-dry_run: true::
+`dry_run: true`::
 Pass `dry_run: true` to either operation to compute the result without writing any file.
 The `result.diff` file contains the rendered content (`init`) or a unified diff (`sync`).
 
@@ -394,10 +455,10 @@ If you are building a Jekyll-compatible templating pipeline, prefer Liquid.
 If you want a low-friction Ruby template for internal tooling, ERB is available.
 
 [[pipelines]]
-=== Prebuild and Rendering Pipelines
+=== Pre-build and Rendering Pipelines
 
-Sourcerer's rendering pipeline is optimized for build tooling and prebuild steps.
-A typical prebuild might load attributes from `README.adoc`, extract tagged snippets into `build/snippets/`, and render YAML plus Liquid templates into `build/docs/`.
+Sourcerer's rendering pipeline is optimized for build tooling and pre-build steps.
+A typical pre-build might load attributes from `README.adoc`, extract tagged snippets into `build/snippets/`, and render YAML plus Liquid templates into `build/docs/`.
 
 The API is intentionally small.
 Sourcerer focuses on producing artifacts, not managing a broader build lifecycle.
@@ -436,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:
@@ -444,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
@@ -463,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::
@@ -491,7 +557,6 @@ require 'asciidoctor/extensions/source-skim-tree-processor/extension'
 Asciidoctor::Extensions.register Sourcerer::SourceSkim::TreeProcessorExtension
 ----
 
-
 [[utilities]]
 === Utilities
 
@@ -518,18 +583,18 @@ Sourcerer::Util::ListAmend.apply(default_list, custom_list, normalize: nil) -> A
 ----
 
 Behavior::
-  `nil` / empty custom:::
-    Returns `default_list` (stringified) unchanged.
-  Fixed-list mode:::
-    If `custom_list` contains *no* tokens starting with `+` or `-`, it fully replaces `default_list`.
-  Amendment mode:::
-    If `custom_list` contains *any* `+`/`-` token:
-    `-slug` removes `slug` from the working set (or no-op if absent). +
-    `+slug` adds `slug` if not already present. +
-    bare `slug` is treated as `+slug`.
+`nil` / empty custom:::
+  Returns `default_list` (stringified) unchanged.
+Fixed-list mode:::
+  If `custom_list` contains *no* tokens starting with `+` or `-`, it fully replaces `default_list`.
+Amendment mode:::
+  If `custom_list` contains *any* `+`/`-` token:
+  `-slug` removes `slug` from the working set (or no-op if absent). +
+  `+slug` adds `slug` if not already present. +
+  bare `slug` is treated as `+slug`.
 
 `normalize` (optional)::
-  A callable used to compare items during deduplication and removal, for example `->(s) { s.downcase }`.
+A callable used to compare items during de-duplication and removal, for example `->(s) { s.downcase }`.
 
 .Examples
 [source,ruby]
@@ -573,7 +638,7 @@ result = Sourcerer::Util::Pathifier.match(input, recursive: true, include_dirs:
 Classification rules::
 `:file`:::    `File.file?(input)` is true.
 `:dir`:::     `File.directory?(input)` is true.
-`:glob`:::    Input contains glob metacharacters (`* ? [ ] { }`).
+`:glob`:::    Input contains glob meta-characters (`* ? [ ] { }`).
 `:missing`::: None of the above.
 
 Options::
@@ -621,7 +686,7 @@ Sourcerer provides it with primitives such as YAML loading, templating, and Liqu
 SchemaGraphy depends on AsciiSourcerer for these primitives, not the other way around.
 
 https://github.com/DocOps/releasehx[ReleaseHx]::
-The ReleaseHx API and `rhx` CLI uses Sourcerer for generating source files during a prebuild stage, and at runtime for YAML ingest and template rendering.
+The ReleaseHx API and `rhx` CLI uses Sourcerer for generating source files during a pre-build stage, and at runtime for YAML ingest and template rendering.
 
 LiquiDoc::
 Secondary to SchemaGraphy, the scriptable template-rendering build utility LiquiDoc will use SchemaGraphy and AsciiSourcerer at runtime.
@@ -754,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
 
@@ -810,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.