docs: add a runnable script-driven generator example

This adds a self-contained search-index generator that the docs page
includes and CI runs.

The extensions/script-driven-generators.adoc example section now
includes the manifest and the generate.lua from this fixture, so the
documented example is exactly the one the test runs.

Author: gennaroprota

CMakeLists.txt

@@ -567,6 +567,19 @@ if (MRDOCS_BUILD_TESTS)
         endforeach ()
     endforeach ()
 
+    #-------------------------------------------------
+    # Script-driven generator example
+    #-------------------------------------------------
+    add_test(
+        NAME mrdocs-generator-script-driven-search-index
+        COMMAND bash run.sh
+                --addons=${CMAKE_CURRENT_SOURCE_DIR}/share/mrdocs/addons
+                --output=${CMAKE_CURRENT_BINARY_DIR}/generator-examples/search-index/reference-output
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/examples/generators/script-driven/search-index
+    )
+    set_property(TEST mrdocs-generator-script-driven-search-index PROPERTY
+        ENVIRONMENT "MRDOCS=$<TARGET_FILE:mrdocs>")
+
     #-------------------------------------------------
     # Library-usage examples
     #

docs/antora-playbook.yml

@@ -71,6 +71,8 @@ antora:
           strip_page_wrapper: true
         - source: examples/generators/data-driven
           target: data-driven-generators
+        - source: examples/generators/script-driven
+          target: script-driven-generators
         - source: examples
           target: examples
     - require: ./extensions/commands-registry-extension.js

docs/modules/ROOT/pages/extensions/script-driven-generators.adoc

@@ -49,28 +49,22 @@ Unlike a corpus-transform extension, whose hook is optional, a generator must de
 
 == Example: a search index
 
-This generator emits a single search-index.json aggregating every symbol, an artifact no per-page generator can produce:
+A complete, runnable example lives at `examples/generators/script-driven/search-index/`. It emits a single search-index.json aggregating every symbol, an artifact no per-page generator can produce.
 
-[source,lua]
+The manifest names the script:
+
+.`addons/generator/search-index/mrdocs-generator.yml`
+[source,yaml]
+----
+include::example$script-driven-generators/search-index/addons/generator/search-index/mrdocs-generator.yml[]
 ----
--- Quote a string as a JSON value.
-local function json_string(s)
-  s = s:gsub('\\', '\\\\'):gsub('"', '\\"')
-  return '"' .. s .. '"'
-end
 
-function generate(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
+The script itself:
+
+.`addons/generator/search-index/generate.lua`
+[source,lua]
 ----
+include::example$script-driven-generators/search-index/addons/generator/search-index/generate.lua[]
+----
+
+Select it with `--generator=search-index`; it writes search-index.json into the output directory.

examples/generators/script-driven/search-index/addons/generator/search-index/generate.lua

@@ -0,0 +1,20 @@
+-- Quote a string as a JSON value.
+local function json_string(s)
+  s = s:gsub('\\', '\\\\'):gsub('"', '\\"')
+  return '"' .. s .. '"'
+end
+
+function generate(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

examples/generators/script-driven/search-index/addons/generator/search-index/mrdocs-generator.yml

@@ -0,0 +1 @@
+script: generate.lua

examples/generators/script-driven/search-index/mrdocs.yml

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

examples/generators/script-driven/search-index/run.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exec "${MRDOCS:-mrdocs}" --config=mrdocs.yml "$@"

examples/generators/script-driven/search-index/simple.cpp

@@ -0,0 +1,16 @@
+/// A point.
+struct Point
+{
+    /** Distance from the origin.
+
+        @return The distance from the origin.
+    */
+    double length() const;
+
+    /** Translate the point by an offset.
+
+        @param dx Horizontal offset.
+        @param dy Vertical offset.
+    */
+    void translate(int dx, int dy);
+};