refactor: define filters via toml file

mknodes/jinja/filters.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import jinja2
+
+from mknodes.jinja import nodeenvironment
+
+
+if TYPE_CHECKING:
+    import types
+
+    import griffe
+
+    import mknodes as mk
+
+
+@jinja2.pass_environment
+def get_link(
+    env: nodeenvironment.NodeEnvironment,
+    target,
+    title: str | None = None,
+) -> str:
+    """Return a markdown link for given target.
+
+    Target can be a class, a module, a MkPage, MkNav or a string.
+
+    Arguments:
+        env: jinja environment
+        target: The thing to link to
+        title: The title to use for the link
+    """
+    return env.node.ctx.links.get_link(target, title)
+
+
+@jinja2.pass_environment
+def get_url(env: nodeenvironment.NodeEnvironment, target) -> str:
+    """Return a markdown link for given target.
+
+    Target can be a class, a module, a MkPage, MkNav or a string.
+
+    Arguments:
+        env: jinja environment
+        target: The thing to link to
+    """
+    return env.node.ctx.links.get_url(target)
+
+
+@jinja2.pass_environment
+def link_for_class(
+    env: nodeenvironment.NodeEnvironment,
+    kls: type | str | griffe.Class,
+) -> str:
+    """Return a markdown link for given class.
+
+    Arguments:
+        env: jinja environment
+        kls: Klass to get a link for
+    """
+    return env.node.ctx.links.link_for_klass(kls)
+
+
+@jinja2.pass_environment
+def link_for_module(
+    env: nodeenvironment.NodeEnvironment,
+    module: types.ModuleType | str | griffe.Module,
+) -> str:
+    """Return a markdown link for given module.
+
+    Arguments:
+        env: jinja environment
+        module: Klass to get a link for
+    """
+    return env.node.ctx.links.link_for_module(module)
+
+
+def to_html(node: mk.MkNode) -> str:
+    """Return HTML for given node.
+
+    Arguments:
+        node: The node to add a mod to
+    """
+    return node.to_html()
+
+
+def apply_mod(node: mk.MkNode, mod_name: str, **kwargs) -> mk.MkNode:
+    """Apply a mod to given node.
+
+    Arguments:
+        node: The node to add a mod to
+        mod_name: The name of the modification to add
+        kwargs: Keyword arguments for the mod ctor
+    """
+    node.mods.add_mod(mod_name, **kwargs)
+    return node

mknodes/jinja/filters.toml

@@ -0,0 +1,53 @@
+[filters.get_link]
+fn = "mknodes.jinja.filters.get_link"
+group = "node"
+
+[filters.get_link.examples.class]
+template = """
+{{ _mk.MkAdmonition | get_link }}
+"""
+
+
+[filters.get_url]
+fn = "mknodes.jinja.filters.get_url"
+group = "node"
+
+[filters.get_url.examples.class]
+template = """
+{{ _mk.MkAdmonition | get_url }}
+"""
+
+
+[filters.link_for_class]
+fn = "mknodes.jinja.filters.link_for_class"
+group = "node"
+
+[filters.link_for_class.examples.class]
+template = """
+{{ _mk.MkAdmonition | link_for_class }}
+"""
+
+
+[filters.link_for_module]
+fn = "mknodes.jinja.filters.link_for_module"
+group = "node"
+
+
+[filters.to_html]
+fn = "mknodes.jinja.filters.to_html"
+group = "node"
+
+[filters.to_html.examples.class]
+template = """
+{{ "test" | MkAdmonition | to_html }}
+"""
+
+
+[filters.apply_mod]
+fn = "mknodes.jinja.filters.apply_mod"
+group = "node"
+
+[filters.apply_mod.examples.class]
+template = """
+{{ "test" | MkAdmonition | apply_mod("ParallaxEffect") }}
+"""

mknodes/jinja/nodeenvironment.py

@@ -51,17 +51,14 @@ def __init__(self, node: mk.MkNode, **kwargs: Any):
         self.class_path = pathlib.Path(path or "").parent.as_posix()
         paths = self.get_extra_paths()
         self.add_template_path(*paths)
+        file = pathlib.Path(__file__).parent / "filters.toml"
+        self.load_jinja_file(file)
+
         import mknodes as mk
 
         self._node_filters = {}
         self._wrapped_klasses = {}
 
-        def apply_mod(node: mk.MkNode, mod_name: str, **kwargs) -> mk.MkNode:
-            node.mods.add_mod(mod_name, **kwargs)
-            return node
-
-        self.filters["apply_mod"] = apply_mod
-
         for kls_name in mk.__all__:
             klass = getattr(mk, kls_name)
 
@@ -97,12 +94,6 @@ def setup_environment(self):
         self.globals["node"] = self.node
         self.globals["file"] = self.node.nodefile
         self.globals["mk"] = self._wrapped_klasses
-        # def update_env_from_context(self):
-        self.filters["get_link"] = self.node.ctx.links.get_link
-        self.filters["get_url"] = self.node.ctx.links.get_url
-        self.filters["link_for_class"] = self.node.ctx.links.link_for_klass
-        self.filters["link_for_module"] = self.node.ctx.links.link_for_module
-        self.filters["to_html"] = lambda x: x.to_html()
         self.globals |= self.node.ctx.as_dict()
 
     def get_extra_paths(self) -> list[str]: