diff --git a/docs/index.rst b/docs/index.rst index 437b5db..dac4a37 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -129,6 +129,22 @@ To see the rendered templates in the built documentation, use the ``debug`` opti Hallo **{{ name }}**! + + +Raw output +********** + +The role can be used to produce raw ouput instead of interpreted RST: + +.. jinja2-example:: + + .. jinja:: + :ctx: {"name": "World"} + :raw: html + + Hello {{ name }} + + Warning messages **************** @@ -141,6 +157,37 @@ Warning messages are displayed in the Sphinx build output, for problematic input Since is difficult / impossible to map the source line numbers, from the template to the Jinja rendered content, problems with the parsing of the rendered content always refer to the first line number either of the ``jinja`` directive, or the template file (when using the ``file`` option). + +Known issues +------------- + +* [#3](https://github.com/sphinx-extensions2/sphinx-jinja2/issues/3): template output is fed back into the RST parser. When the source uses `MyST parser `__, this will trigger an error:: + + Directive 'jinja' cannot be mocked: MockingError: MockStateMachine has not yet implemented 'insert_input'. + + + The workaround is to wrap the `jinja` directive inside `rst-eval` + + .. code-block:: rst + + ```{rst-eval} + .. jinja:: + :ctx: {"foo":"bar"} + + Baz. + ``` + + rather than using it directly: + + .. code-block:: markdown + + ```{jinja} + :ctx: {"foo":"bar"} + + Baz. + ``` + + Configuration ------------- diff --git a/src/sphinx_jinja2/__init__.py b/src/sphinx_jinja2/__init__.py index 1e5c7fb..68bcd1f 100644 --- a/src/sphinx_jinja2/__init__.py +++ b/src/sphinx_jinja2/__init__.py @@ -97,6 +97,7 @@ class JinjaDirective(SphinxDirective): "file": directives.path, "ctx": directives.unchanged, "debug": directives.flag, + "raw": directives.unchanged, } options: JinjaOptions arguments: list[str] @@ -187,12 +188,20 @@ def _warn(msg: str) -> None: _warn(f"Error rendering jinja template: {exc.__class__.__name__}: {exc}") return [] - # insert the new content into the source stream - # setting the source and line number - new_lines = StringList( - new_content.splitlines(), items=[(source, line - 1) for _ in new_content.splitlines()] - ) - self.state_machine.insert_input(new_lines, source) + if "raw" not in self.options: + # insert the new content into the source stream + # setting the source and line number + new_lines = StringList( + new_content.splitlines(), + items=[(source, line - 1) for _ in new_content.splitlines()], + ) + self.state_machine.insert_input(new_lines, source) + else: + raw_node = nodes.raw( + "", new_content, classes="jinja-rendered", format=self.options["raw"] + ) + (raw_node.source, raw_node.line) = self.state_machine.get_source_and_line(self.lineno) + return [raw_node] if conf.debug or "debug" in self.options: # return the rendered template