feat: declare output generators from extension scripts

An extension script now defines an output generator with
`register_generator(id, fn)`, alongside any `register_transform` it
declares, rather than a generator directory shipping a
mrdocs-generator.yml that names a script. Both hooks receive one `ctx`
object: `ctx.corpus` and `ctx.config` for a transform, and additionally
`ctx.output` for a generator. This replaces the positional
`generate(corpus, output, config, params)` entry point and the separate
manifest-script discovery pass.

A registered generator is a `dom::Function` the corpus owns, because the
generator registry is a process-global that is never cleared. The build
populates the corpus with the registered generators while extensions
run; `GenerateAction` then resolves the requested generator from the
corpus before falling back to the registry. A single language-agnostic
runner invokes the function, so the two per-language generator runners
collapse into one path.

The manifest now carries only the data-driven generator fields, its
escape rules and the parent it extends; the `script` and `params` keys
are gone. The search-index example moves under addons/extensions and
declares its generator with `register_generator`.

Author: gennaroprota

CMakeLists.txt

@@ -483,6 +483,7 @@ if (MRDOCS_BUILD_TESTS)
             "${PROJECT_BINARY_DIR}/src"
             )
     target_link_libraries(mrdocs-test PUBLIC mrdocs-core)
+    target_link_libraries(mrdocs-test PRIVATE Lua::lua)
     if (MRDOCS_CLANG)
         target_compile_options(mrdocs-test PRIVATE -Wno-covered-switch-default)
     endif ()

docs/mrdocs.schema.json

@@ -282,7 +282,7 @@
       "default": [
         "html"
       ],
-      "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`, `xml`, and `noop` (which extracts but writes no output, useful for checking extraction warnings); 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. This option accepts a single generator (`generator: xml`), a list (`generator: [xml, adoc]`), or a comma-separated string (`generator: \"xml,adoc\"`); when more than one is given the documentation is produced once per generator.",
+      "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`, `xml`, and `noop` (which extracts but writes no output, useful for checking extraction warnings); data-driven generators can be added by dropping a template folder under <addon>/generator/<name>/; a script-driven generator is declared by an extension with `register_generator` and produces the output itself. This option accepts a single generator (`generator: xml`), a list (`generator: [xml, adoc]`), or a comma-separated string (`generator: \"xml,adoc\"`); when more than one is given the documentation is produced once per generator.",
       "title": "Generator(s) used to create the documentation"
     },
     "global-namespace-index": {

examples/generators/script-driven/search-index/addons/extensions/search_index.lua

@@ -0,0 +1,30 @@
+-- Declare a "search-index" generator: a script-defined generator that
+-- aggregates every symbol into a single search-index.json, the kind of
+-- artifact the per-page generators cannot produce.
+--
+-- register_generator(id, fn) declares it next to any register_transform a
+-- script might also declare; selecting "generator: <id>" runs fn with one
+-- ctx. ctx.corpus.symbols is every symbol (each tagged with a flat _id so
+-- the generator can form stable per-symbol URLs) and ctx.output.write
+-- emits files under the output directory.
+
+-- Quote a string as a JSON value.
+local function json_string(s)
+  s = s:gsub('\\', '\\\\'):gsub('"', '\\"')
+  return '"' .. s .. '"'
+end
+
+register_generator("search-index", function(ctx)
+  local entries = {}
+  for _, sym in ipairs(ctx.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
+  ctx.output.write(
+    "search-index.json",
+    "[" .. table.concat(entries, ",") .. "]")
+end)

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

@@ -443,7 +443,7 @@
       {
         "name": "generator",
         "brief": "Generator(s) 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`, `xml`, and `noop` (which extracts but writes no output, useful for checking extraction warnings); 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. This option accepts a single generator (`generator: xml`), a list (`generator: [xml, adoc]`), or a comma-separated string (`generator: \"xml,adoc\"`); when more than one is given the documentation is produced once per generator.",
+        "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`, `xml`, and `noop` (which extracts but writes no output, useful for checking extraction warnings); data-driven generators can be added by dropping a template folder under <addon>/generator/<name>/; a script-driven generator is declared by an extension with `register_generator` and produces the output itself. This option accepts a single generator (`generator: xml`), a list (`generator: [xml, adoc]`), or a comma-separated string (`generator: \"xml,adoc\"`); when more than one is given the documentation is produced once per generator.",
         "type": "string-list",
         "default": ["html"]
       },

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

@@ -1102,4 +1102,36 @@ CorpusImpl::finalize()
     }
 }
 
+void
+CorpusImpl::
+registerScriptGenerator(std::string id, dom::Function fn)
+{
+    if (findScriptGenerator(id) == nullptr)
+    {
+        scriptGenerators_.emplace_back(std::move(id), std::move(fn));
+    }
+}
+
+dom::Function const*
+CorpusImpl::
+findScriptGenerator(std::string_view id) const noexcept
+{
+    dom::Function const* result = nullptr;
+    for (auto const& entry : scriptGenerators_)
+    {
+        if (result == nullptr && std::string_view(entry.first) == id)
+        {
+            result = &entry.second;
+        }
+    }
+    return result;
+}
+
+void
+CorpusImpl::
+keepScriptVmAlive(std::shared_ptr<void> keepAlive)
+{
+    scriptVmKeepAlives_.push_back(std::move(keepAlive));
+}
+
 } // mrdocs

src/lib/ConfigOptions.json

@@ -20,14 +20,19 @@
 #include <lib/Support/Debug.hpp>
 #include <mrdocs/ADT/UnorderedStringMap.hpp>
 #include <mrdocs/Corpus.hpp>
+#include <mrdocs/Dom.hpp>
 #include <mrdocs/Metadata.hpp>
 #include <mrdocs/Support/Error.hpp>
 #include <clang/Tooling/CompilationDatabase.h>
 #include <functional>
 #include <map>
+#include <memory>
 #include <mutex>
 #include <set>
 #include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
 
 namespace mrdocs {
 
@@ -56,6 +61,22 @@ class CorpusImpl final : public Corpus
     // The value is another map from the name to the Info.
     std::map<SymbolID, UnorderedStringMap<Symbol const*>> lookupCache_;
 
+    // Output generators an extension script defined via
+    // `register_generator(id, fn)`. Each `fn` is a `dom::Function` that
+    // stays runnable until this corpus is destroyed (after extensions run,
+    // when a generator is selected). Its scripting VM is kept alive either
+    // by the function itself or by a matching entry in
+    // `scriptVmKeepAlives_`. First registration of an id wins; later ones
+    // are ignored.
+    std::vector<std::pair<std::string, dom::Function>> scriptGenerators_;
+
+    // Strong references to scripting VMs that back `scriptGenerators_` but
+    // are only weakly held by the generator functions themselves (the
+    // JavaScript backend works this way). Keeping a reference here lets
+    // such a generator outlive the extension run that defined it, up to
+    // this corpus's destruction.
+    std::vector<std::shared_ptr<void>> scriptVmKeepAlives_;
+
     friend class Corpus;
     friend class BaseMembersFinalizer;
     friend class OverloadsFinalizer;
@@ -194,6 +215,29 @@ class CorpusImpl final : public Corpus
     void
     finalize();
 
+    /** Register a script-defined output generator.
+
+        Called from an extension's `register_generator(id, fn)`. The first
+        registration of a given id wins; later ones are ignored.
+    */
+    void
+    registerScriptGenerator(std::string id, dom::Function fn);
+
+    /** Return the script-defined generator with this id, or `nullptr`.
+    */
+    dom::Function const*
+    findScriptGenerator(std::string_view id) const noexcept;
+
+    /** Keep a scripting VM alive for the lifetime of this corpus.
+
+        A generator registered via `register_generator` may hold only a
+        weak reference to the VM that defined it. The extension binding
+        hands the VM over here so it outlives the extension run and stays
+        usable when the generator is selected.
+    */
+    void
+    keepScriptVmAlive(std::shared_ptr<void> keepAlive);
+
 private:
     /** Return the Info with the specified symbol ID.
 

src/lib/CorpusImpl.cpp

@@ -151,4 +151,13 @@ buildCorpusDom(CorpusImpl& corpus)
     return dom::Value(std::move(corpusObj));
 }
 
+dom::Value
+buildTransformContext(CorpusImpl& corpus)
+{
+    dom::Object ctx;
+    ctx.set("corpus", buildCorpusDom(corpus));
+    ctx.set("config", dom::Value(corpus.config.object()));
+    return dom::Value(std::move(ctx));
+}
+
 } // mrdocs

src/lib/CorpusImpl.hpp

@@ -15,8 +15,7 @@ namespace mrdocs {
 
 class CorpusImpl;
 
-/** Build the `corpus` argument passed to each registered corpus
-    transform.
+/** Build the `ctx.corpus` object seen by extension scripts.
 
     The returned value is a small object:
 
@@ -33,6 +32,18 @@ class CorpusImpl;
 dom::Value
 buildCorpusDom(CorpusImpl& corpus);
 
+/** Build the `ctx` argument passed to each registered corpus transform.
+
+    A transform receives one object so new capabilities can be added
+    without changing its signature:
+
+    - `ctx.corpus` -- the navigable corpus (see @ref buildCorpusDom) the
+      transform reads and mutates in place.
+    - `ctx.config` -- the generation configuration.
+*/
+dom::Value
+buildTransformContext(CorpusImpl& corpus);
+
 } // mrdocs
 
 #endif