docs: document script-driven generators

Author: gennaroprota

docs/modules/ROOT/pages/generators.adoc

@@ -200,6 +200,76 @@ Unknown top-level keys are silently ignored so future schema additions stay non-
 If the same id appears under more than one addon root, the first one wins: that root's manifest sets the format's escape rules.
 Later roots can still contribute layered partials and helpers under the same id through the existing template-loading path, so a project can supplement a shared format without redefining it.
 
+To add a generator that builds its output structure imperatively, rather than rendering one page per symbol from templates, see <<script-driven-generators,Script-driven generators>>.
+
+[#script-driven-generators]
+== Script-driven generators
+
+A data-driven generator renders one page per symbol from templates. When you need a different output structure - one file per namespace, or a single artifact aggregated across every symbol, such as a search index - a template generator cannot express it, because the page-per-symbol shape is fixed by the host. A script-driven generator hands the whole emit to a Lua or JavaScript script, which traverses the corpus and writes whatever files it wants. No C++ and no templates are involved.
+
+A generator directory is script-driven when its `mrdocs-generator.yml` names an entry script:
+
+[source,yaml]
+----
+script: generator.lua
+----
+
+The `script` key holds a path to a Lua (`.lua`) or JavaScript (`.js`) file, relative to the generator directory. Naming a script is what distinguishes the two flavors: a manifest with a `script` key is script-driven, otherwise the directory is a data-driven (template) generator. As with template generators, the directory name is the generator id you select with `--generator`.
+
+=== The `generate` entry point
+
+The script defines a single entry point:
+
+[source]
+----
+generate(corpus, output)
+----
+
+`corpus.symbols` is the array of every symbol. Each symbol carries the same fields the template and helper layers see, plus a flat `_id` string suitable as a stable per-symbol URL fragment.
+
+`output.write(relativePath, contents)` writes one file. The path is resolved under the output directory and may not escape it; an absolute path or one that climbs above the output directory is rejected. Parent directories are created as needed.
+
+Because the script owns the output, it also owns what a per-page generator would otherwise do for it: the URLs it emits, and any escaping of the content it writes. The host does not apply an escape map to a script-driven generator's output.
+
+In Lua, `generate` may be the value the script returns or a global function; in JavaScript it is a global function:
+
+[source,lua]
+----
+return function(corpus, output)
+  -- ...
+end
+----
+
+Unlike a corpus-transform extension, whose hook is optional, a generator must define a `generate` function: selecting the generator is a request for output, so a missing entry point is an error.
+
+=== Example: a search index
+
+This generator emits a single search-index.json aggregating every symbol, an artifact no per-page generator can produce:
+
+[source,lua]
+----
+-- Quote a string as a JSON value.
+local function json_string(s)
+  s = s:gsub('\\', '\\\\'):gsub('"', '\\"')
+  return '"' .. s .. '"'
+end
+
+return function(corpus, output)
+  local entries = {}
+  for _, sym in ipairs(corpus.symbols) do
+    local name = sym.name or ""
+    if name ~= "" then
+      entries[#entries + 1] =
+        '{"name":' .. json_string(name) ..
+        ',"url":' .. json_string(sym._id .. ".html") .. "}"
+    end
+  end
+  output.write(
+    "search-index.json",
+    "[" .. table.concat(entries, ",") .. "]")
+end
+----
+
 == Stylesheet Options
 
 The HTML and AsciiDoc generators ship a bundled stylesheet that is inlined by default. You can replace or layer styles with the following options (available in config files and on the CLI):

docs/mrdocs.schema.json

@@ -252,7 +252,7 @@
     },
     "generator": {
       "default": "adoc",
-      "description": "The generator is responsible for creating the documentation from the extracted symbols. The generator uses the extracted symbols and the templates to create the documentation. The built-in generators include `adoc`, `html`, and `xml`; data-driven generators can be added by dropping a template folder under <addon>/generator/<name>/.",
+      "description": "The generator is responsible for creating the documentation from the extracted symbols. The generator uses the extracted symbols and the templates to create the documentation. The built-in generators include `adoc`, `html`, and `xml`; data-driven generators can be added by dropping a template folder under <addon>/generator/<name>/; script-driven generators instead ship a Lua or JavaScript script that produces the output.",
       "title": "Generator used to create the documentation",
       "type": "string"
     },

src/lib/ConfigOptions.json

@@ -397,7 +397,7 @@
       {
         "name": "generator",
         "brief": "Generator used to create the documentation",
-        "details": "The generator is responsible for creating the documentation from the extracted symbols. The generator uses the extracted symbols and the templates to create the documentation. The built-in generators include `adoc`, `html`, and `xml`; data-driven generators can be added by dropping a template folder under <addon>/generator/<name>/.",
+        "details": "The generator is responsible for creating the documentation from the extracted symbols. The generator uses the extracted symbols and the templates to create the documentation. The built-in generators include `adoc`, `html`, and `xml`; data-driven generators can be added by dropping a template folder under <addon>/generator/<name>/; script-driven generators instead ship a Lua or JavaScript script that produces the output.",
         "type": "string",
         "default": "adoc"
       },

test-files/template-only-generators/search-index/addons/generator/search-index/generator.lua

@@ -0,0 +1,34 @@
+-- A script-driven generator.
+--
+-- Where a per-page generator writes one file per symbol, this one emits
+-- a single search-index.json aggregating every symbol. That aggregated
+-- shape is exactly what the per-page generators cannot produce, and the
+-- reason a generator owns its emit loop.
+--
+-- The entry point is `generate(corpus, output)`:
+--   `corpus.symbols` is the array of symbols, each with a `name` and
+--   a flat `_id` usable as a stable per-symbol URL fragment.
+--   `output.write(relativePath, contents)` writes one file under the
+--   output directory.
+
+-- Quote a string as a JSON value, escaping the two characters that a
+-- bare double-quoted JSON string may not contain literally.
+local function json_string(s)
+  s = s:gsub('\\', '\\\\'):gsub('"', '\\"')
+  return '"' .. s .. '"'
+end
+
+return function(corpus, output)
+  local entries = {}
+  for _, sym in ipairs(corpus.symbols) do
+    local name = sym.name or ""
+    if name ~= "" then
+      entries[#entries + 1] =
+        '  {"name":' .. json_string(name) ..
+        ',"url":' .. json_string(sym._id .. ".html") .. "}"
+    end
+  end
+  output.write(
+    "search-index.json",
+    "[\n" .. table.concat(entries, ",\n") .. "\n]\n")
+end

test-files/template-only-generators/search-index/addons/generator/search-index/mrdocs-generator.yml

@@ -0,0 +1,5 @@
+# A script-driven generator. The script named here owns the whole
+# emit: it walks the corpus and writes whatever files it wants through
+# the output object. Naming a script is what marks this directory as a
+# script-driven generator rather than a data-driven (template) one.
+script: generator.lua

test-files/template-only-generators/search-index/mrdocs.yml

@@ -0,0 +1,7 @@
+addons-supplemental:
+  - addons
+generator: search-index
+multipage: false
+show-namespaces: false
+warn-if-undocumented: false
+source-root: .

test-files/template-only-generators/search-index/simple.cpp

@@ -0,0 +1,16 @@
+// A small input for the search-index example generator. The generator
+// walks every symbol and emits a single aggregated search-index.json,
+// so a handful of distinct names is enough to show the aggregation.
+
+/// Add two integers.
+int add(int a, int b);
+
+/// Subtract two integers.
+int subtract(int a, int b);
+
+/// A point in the plane.
+struct Point
+{
+    int x;
+    int y;
+};