Implement and document the raw option

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 <em>{{ name }}</em>
+
+
 Warning messages
 ****************
 

src/sphinx_jinja2/__init__.py

@@ -88,6 +88,8 @@ class JinjaOptions(TypedDict, total=False):
     relative to current file, or src directory (if starts with ``/``) """
     debug: bool
     """Also output the rendered template"""
+    raw: str
+    """The rendered template is raw output in given format, rather than input put back into the source parser."""
 
 
 class JinjaDirective(SphinxDirective):
@@ -97,6 +99,7 @@ class JinjaDirective(SphinxDirective):
         "file": directives.path,
         "ctx": directives.unchanged,
         "debug": directives.flag,
+        "raw": directives.unchanged,
     }
     options: JinjaOptions
     arguments: list[str]
@@ -187,12 +190,18 @@ 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=[], 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