mrdocs::PluginContext::registerGenerator

Register a generator from an id and a callable.

Synopsis

Declared in <mrdocs/Plugin.hpp>

template<class F>
requires std::copy_constructible<std::decay_t<F>> &&
        std::is_invocable_r_v<
            Expected<void>,
            std::decay_t<F>&,
            GeneratorExtensionContext const&>
Expected<void>
registerGenerator(
    std::string_view id,
    F&& fn,
    std::string_view displayName = {},
    std::string_view fileExtension = {});

Description

The callable is the generator's whole job, the way the function a script passes to mrdocs.register_generator is. It is called with a GeneratorExtensionContext each time the generator runs, and returns an error to stop the run. MrDocs wraps it in a Generator whose Generator::id is id and registers that with the overload above, so the same rules apply: the generator is selectable under id, and one with that id already registered is refused.

The callable is copied for each call, so state it captures does not carry from one call to the next and it has to be copy constructible; use the overload above for a generator that keeps state across calls. The callable must not throw: it reports a failure by returning an error, the way the generator does.

return context.registerGenerator("notes",
    [](mrdocs::GeneratorExtensionContext const& ctx) -> mrdocs::Expected<void>
    {
        // write files under ctx.outputPath
        return {};
    });

Return Value

An error if a generator with the same id is already registered.

Parameters

Name

Description

id

The generator's id.

fn

A callable taking a GeneratorExtensionContext const& and returning Expected<void>.

displayName

The generator's display name; id when empty.

fileExtension

The generator's file extension, without a leading period; empty by default.

Created with MrDocs