nixos-render-docs: add example blocks

this is currently only supported by the docbook exporter, and even the
docbook exporter doesn't do much with them. we mirror the conversion
pandoc did for consistency with the previous manual chapter conversion,
which is to add just an anchor with the given id. future exporters that
go directly to html might want to do more.

3 files changed, 52 insertions, 1 deletions

diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py
index 1f0e07650e2..b3728645f75 100644
--- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py
+++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py
@@ -252,6 +252,14 @@ class DocBookRenderer(Renderer):
     def heading_close(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,
                       env: MutableMapping[str, Any]) -> str:
         return '</title>'
+    def example_open(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,
+                     env: MutableMapping[str, Any]) -> str:
+        if id := token.attrs.get('id'):
+            return f"<anchor xml:id={quoteattr(cast(str, id))} />"
+        return ""
+    def example_close(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,
+                      env: MutableMapping[str, Any]) -> str:
+        return ""
 
     def _close_headings(self, level: Optional[int], env: MutableMapping[str, Any]) -> str:
         # we rely on markdown-it producing h{1..6} tags in token.tag for this to work
diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/md.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/md.py
index 5c824a25c0c..599ee7e91c1 100644
--- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/md.py
+++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/md.py
@@ -28,7 +28,7 @@ _md_escape_table = {
 def md_escape(s: str) -> str:
     return s.translate(_md_escape_table)
 
-AttrBlockKind = Literal['admonition']
+AttrBlockKind = Literal['admonition', 'example']
 
 AdmonitionKind = Literal["note", "caution", "tip", "important", "warning"]
 
@@ -74,6 +74,8 @@ class Renderer(markdown_it.renderer.RendererProtocol):
             "heading_close": self.heading_close,
             "ordered_list_open": self.ordered_list_open,
             "ordered_list_close": self.ordered_list_close,
+            "example_open": self.example_open,
+            "example_close": self.example_close,
         }
 
         self._admonitions = {
@@ -248,6 +250,12 @@ class Renderer(markdown_it.renderer.RendererProtocol):
     def ordered_list_close(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,
                            env: MutableMapping[str, Any]) -> str:
         raise RuntimeError("md token not supported", token)
+    def example_open(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,
+                     env: MutableMapping[str, Any]) -> str:
+        raise RuntimeError("md token not supported", token)
+    def example_close(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,
+                      env: MutableMapping[str, Any]) -> str:
+        raise RuntimeError("md token not supported", token)
 
 def _is_escaped(src: str, pos: int) -> bool:
     found = 0
@@ -288,6 +296,8 @@ def _parse_blockattrs(info: str) -> Optional[tuple[AttrBlockKind, Optional[str],
         if id is not None:
             return None
         return ('admonition', id, classes)
+    if classes == ['example']:
+        return ('example', id, classes)
     return None
 
 def _attr_span_plugin(md: markdown_it.MarkdownIt) -> None:
@@ -432,6 +442,11 @@ def _block_attr(md: markdown_it.MarkdownIt) -> None:
                     token.type = 'admonition_open'
                     token.meta['kind'] = classes[0]
                     stack.append('admonition_close')
+                elif kind == 'example':
+                    token.type = 'example_open'
+                    if id is not None:
+                        token.attrs['id'] = id
+                    stack.append('example_close')
                 else:
                     assert_never(kind)
             elif token.type == 'container_blockattr_close':
diff --git a/pkgs/tools/nix/nixos-render-docs/src/tests/test_plugins.py b/pkgs/tools/nix/nixos-render-docs/src/tests/test_plugins.py
index db05d6253c8..1d836a916d9 100644
--- a/pkgs/tools/nix/nixos-render-docs/src/tests/test_plugins.py
+++ b/pkgs/tools/nix/nixos-render-docs/src/tests/test_plugins.py
@@ -422,3 +422,31 @@ def test_admonitions() -> None:
         Token(type='admonition_close', tag='div', nesting=-1, attrs={}, map=None, level=0,
               children=None, content='', markup=':::', info='', meta={}, block=True, hidden=False)
     ]
+
+def test_example() -> None:
+    c = Converter({})
+    assert c._parse("::: {.example}") == [
+        Token(type='example_open', tag='div', nesting=1, attrs={}, map=[0, 1], level=0, children=None,
+              content='', markup=':::', info=' {.example}', meta={}, block=True, hidden=False),
+        Token(type='example_close', tag='div', nesting=-1, attrs={}, map=None, level=0, children=None,
+              content='', markup=':::', info='', meta={}, block=True, hidden=False)
+    ]
+    assert c._parse("::: {#eid .example}") == [
+        Token(type='example_open', tag='div', nesting=1, attrs={'id': 'eid'}, map=[0, 1], level=0,
+              children=None, content='', markup=':::', info=' {#eid .example}', meta={}, block=True,
+              hidden=False),
+        Token(type='example_close', tag='div', nesting=-1, attrs={}, map=None, level=0, children=None,
+              content='', markup=':::', info='', meta={}, block=True, hidden=False)
+    ]
+    assert c._parse("::: {.example .note}") == [
+        Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[0, 1], level=0, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=False),
+        Token(type='inline', tag='', nesting=0, attrs={}, map=[0, 1], level=1,
+              content='::: {.example .note}', markup='', info='', meta={}, block=True, hidden=False,
+              children=[
+                  Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None,
+                        content='::: {.example .note}', markup='', info='', meta={}, block=False, hidden=False)
+              ]),
+        Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=0, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=False)
+    ]