Adapter for converting Qt JSON types to Inja template engine format. More...

#include <injabridge.h>

Collaboration diagram for InjaBridge:

Classes
struct	RenderContext
	Identifies the render a template error belongs to. More...
struct	RenderFailure
	\variable InjaBridge::RenderContext::format More...

Public Types
using	IncludeCallback = std::function<std::optional<QString>(const QString &name)>
using	RenderResult = std::variant<QString, RenderFailure>
	\variable InjaBridge::RenderFailure::message

Static Public Member Functions
static QString	renderErrorText (const RenderContext &context, const QString &message)
	Formats message with the failing render's context.
static nlohmann::json	toInjaJson (const QJsonValue &value)
	Converts a QJsonValue, value, to nlohmann::json.
static nlohmann::json	toInjaJson (const QJsonObject &obj)
	Converts a QJsonObject, obj, to nlohmann::json.
static nlohmann::json	toInjaJson (const QJsonArray &array)
	Converts a QJsonArray, array, to nlohmann::json.
static RenderResult	render (const QString &templateStr, const QJsonObject &data, const RenderContext &context={ })
	Renders a template string, templateStr, with provided data.
static RenderResult	render (const QString &templateStr, const QJsonObject &data, const IncludeCallback &includeCallback, const RenderContext &context={ })
	Renders a template string, templateStr, with provided data, using includeCallback to resolve {{% include %}} directives.
static RenderResult	renderFile (const QString &templatePath, const QJsonObject &data, const RenderContext &context={ })
	Renders a template file with provided data.

Detailed Description

Adapter for converting Qt JSON types to Inja template engine format.

InjaBridge provides static methods to convert between Qt's native JSON types (QJsonObject, QJsonArray, QJsonValue) and nlohmann::json, which is the data format expected by the Inja template engine.

This adapter allows QDoc to maintain its Qt-native API while leveraging Inja for template-based documentation generation. All JSON data in QDoc's intermediate representation (IR) uses Qt types, and InjaBridge handles the conversion when rendering templates.

Note: All numbers in QJsonValue are stored as doubles. Whole-number doubles (e.g., 30.0, 2.0) are converted to int64_t so that template output renders them as integers (e.g., "30" not "30.0"). Fractional values pass through as doubles.; Inja and nlohmann::json may report template or data errors, such as a user template accessing an IR field that a given page does not carry. With exceptions, the render methods return a RenderFailure so the caller can report the error and continue with later pages. Without exceptions, both libraries' error-reporting entry points terminate the run with the same contextual diagnostic.

All render methods register template callbacks: \list

{escape_html()} escapes HTML special characters ({&}, {<}, {>}, {"}, \c{'}). \li \c{escape_md_table()} escapes pipe characters and collapses newlines for safe use inside Markdown table cells. \li \c{render_signature_spans()} converts a JSON array of signature spans (from SignatureSpan IR) into semantic HTML with role-based markup (\c{<span class="type">}, \c{<span class="name">}, etc.). \endlist Escaping callbacks keep format-specific logic under template author control. The {render_signature_spans()} callback centralizes signature rendering that was previously duplicated across multiple templates.

See also: QJsonObject, QJsonArray, QJsonValue

Definition at line 44 of file injabridge.h.

Member Typedef Documentation

◆ IncludeCallback

using InjaBridge::IncludeCallback = std::function<std::optional<QString>(const QString &name)>

Definition at line 47 of file injabridge.h.

◆ RenderResult

using InjaBridge::RenderResult = std::variant<QString, RenderFailure>

\variable InjaBridge::RenderFailure::message

The error message reported by the template engine.

A rendered string or a template render failure.

An empty string is a successful result.

Definition at line 61 of file injabridge.h.

Member Function Documentation

◆ render() [1/2]

InjaBridge::RenderResult InjaBridge::render	(	const QString &	templateStr,
		const QJsonObject &	data,
		const IncludeCallback &	includeCallback,
		const RenderContext &	context = { } )

static

Renders a template string, templateStr, with provided data, using includeCallback to resolve {{% include %}} directives.

This overload configures the Inja environment with a custom include callback so that templates can use {{% include "name" %}} directives. The includeCallback receives the include name and returns the partial's content. An empty string is a valid partial; no value means the include wasn't found and reports a render failure.

This enables Inja's include mechanism to work with Qt's resource system, where {std::ifstream} cannot open {:/} paths.

context identifies the render for error reporting; see \l RenderContext.

Returns the rendered template or a render failure.

Definition at line 497 of file injabridge.cpp.

◆ render() [2/2]

InjaBridge::RenderResult InjaBridge::render	(	const QString &	templateStr,
		const QJsonObject &	data,
		const RenderContext &	context = { } )

static

Renders a template string, templateStr, with provided data.

Uses Inja to render the template with the given JSON data. The data is automatically converted from QJsonObject to nlohmann::json.

The Inja template string, templateStr, supports Jinja2 syntax. data is the JSON data to use for rendering. context identifies the render for error reporting; see \l RenderContext.

Returns the rendered template or a render failure.

Definition at line 460 of file injabridge.cpp.

◆ renderErrorText()

QString InjaBridge::renderErrorText	(	const RenderContext &	context,
		const QString &	message )

static

Formats message with the failing render's context.

Definition at line 47 of file injabridge.cpp.

◆ renderFile()

InjaBridge::RenderResult InjaBridge::renderFile	(	const QString &	templatePath,
		const QJsonObject &	data,
		const RenderContext &	context = { } )

static

Renders a template file with provided data.

Loads and renders a template from the filesystem, using templatePath which holds the absolute path to the template file. The file should use Inja/Jinja2 syntax. data is the JSON data to use for rendering.

context identifies the render for error reporting; see \l RenderContext.

Returns the rendered template or a render failure.

Definition at line 535 of file injabridge.cpp.

◆ toInjaJson() [1/3]

nlohmann::json InjaBridge::toInjaJson ( const QJsonArray & array )

static

Converts a QJsonArray, array, to nlohmann::json.

Recursively converts all elements in the array, preserving order. Mixed-type arrays are supported.

Returns the equivalent nlohmann::json array.

Definition at line 438 of file injabridge.cpp.

◆ toInjaJson() [2/3]

nlohmann::json InjaBridge::toInjaJson ( const QJsonObject & obj )

static

Converts a QJsonObject, obj, to nlohmann::json.

Recursively converts all values in the object, preserving the key-value structure. Nested objects and arrays are handled correctly.

Returns the equivalent nlohmann::json object.

Definition at line 420 of file injabridge.cpp.

◆ toInjaJson() [3/3]

nlohmann::json InjaBridge::toInjaJson ( const QJsonValue & value )

static

Converts a QJsonValue, value, to nlohmann::json.

Handles all QJsonValue types: Null, Bool, Double, String, Array, Object, and Undefined. Undefined values are treated as null.

Returns the equivalent nlohmann::json representation.

Definition at line 387 of file injabridge.cpp.

The documentation for this class was generated from the following files:

qttools/src/qdoc/qdoc/src/qdoc/injabridge.h (d89324ffe39397f535bd6f64c26514887ed3a7ba)
qttools/src/qdoc/qdoc/src/qdoc/injabridge.cpp (d89324ffe39397f535bd6f64c26514887ed3a7ba)

Classes

Public Types

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ IncludeCallback

◆ RenderResult

Member Function Documentation

◆ render() [1/2]

◆ render() [2/2]

◆ renderErrorText()

◆ renderFile()

◆ toInjaJson() [1/3]

◆ toInjaJson() [2/3]

◆ toInjaJson() [3/3]