refactor: Clean up registry APIs

- Expose ExtraContextRegistry with add() method, remove internal get/get_names
- Add JinjaRegistry with add_filter() and add_extension() methods
- Update Registry class with extra_context and jinja_env properties
- Move default Jinja extensions to setup() for proper initialization
- Update documentation and tests

Co-authored-by: MiMoCode <mimo@xiaomi.com>
Co-authored-by: DeepSeek <service@deepseek.com>

Author: 3 people

docs/api.rst

@@ -29,7 +29,7 @@ Base Directive Classes
 
 .. autoclass:: sphinxnotes.render.BaseContextDirective
    :show-inheritance:
-   :members: process_pending_node, queue_pending_node, current_raw_data, current_context, current_template
+   :members: process_pending_node, queue_pending_node, current_context, current_template
 
 .. autoclass:: sphinxnotes.render.BaseDataDefineDirective
    :show-inheritance:
@@ -104,11 +104,19 @@ See :doc:`tmpl` for built-in extra-context names such as ``doc`` and
    :members:
    :undoc-members:
 
+.. autoclass:: sphinxnotes.render.ExtraContextRegistry
+   :members:
+   :undoc-members:
+
 Filters
 =======
 
 .. autodecorator:: sphinxnotes.render.filter
 
+.. autoclass:: sphinxnotes.render.JinjaRegistry
+   :members:
+   :undoc-members:
+
 Data, Field and Schema
 ======================
 
@@ -148,3 +156,7 @@ or add new extra context) by adding new items to
 .. autoclass:: sphinxnotes.render.Registry
 
    .. autoproperty:: data
+
+   .. autoproperty:: extra_context
+
+   .. autoproperty:: jinja

src/sphinxnotes/render/__init__.py

@@ -28,6 +28,8 @@
     extra_context,
     ExtraContext,
     ExtraContextRequest,
+    Registry as ExtraContextRegistry,
+    REGISTRY as EXTRA_CONTEXT_REGISTRY,
 )
 from .pipeline import BaseContextRole, BaseContextDirective
 from .sources import (
@@ -36,7 +38,7 @@
     BaseDataDefineDirective,
     StrictDataDefineDirective,
 )
-from .jinja import filter
+from .jinja import filter, Registry as JinjaRegistry, REGISTRY as JINJA_REGISTRY
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -45,6 +47,7 @@
 """Python API for other Sphinx extensions."""
 __all__ = [
     'Registry',
+    'DataRegistry',
     'PlainValue',
     'Value',
     'ValueWrapper',
@@ -58,6 +61,8 @@
     'ResolvedContext',
     'ExtraContext',
     'ExtraContextRequest',
+    'ExtraContextRegistry',
+    'EXTRA_CONTEXT_REGISTRY',
     'extra_context',
     'pending_node',
     'BaseContextRole',
@@ -67,6 +72,8 @@
     'BaseDataDefineDirective',
     'StrictDataDefineDirective',
     'filter',
+    'JinjaRegistry',
+    'JINJA_REGISTRY',
 ]
 
 
@@ -77,6 +84,14 @@ class Registry:
     def data(self) -> DataRegistry:
         return DATA_REGISTRY
 
+    @property
+    def extra_context(self) -> ExtraContextRegistry:
+        return EXTRA_CONTEXT_REGISTRY
+
+    @property
+    def jinja(self) -> JinjaRegistry:
+        return JINJA_REGISTRY
+
 
 REGISTRY = Registry()
 

src/sphinxnotes/render/ctxnodes.py

@@ -29,17 +29,30 @@
 class pending_node(nodes.Element):
     """A docutils node to be rendered."""
 
-    # The context to be rendered by Jinja template.
+    #: The context to be rendered by Jinja template.
     ctx: UnresolvedContext | ResolvedContext
     #: Jinja template for rendering the context.
     template: Template
     #: Whether rendering to inline nodes.
     inline: bool
     #: Whether the rendering pipeline is finished (failed is also finished).
     rendered: bool
-    #: Stored pickling error for later-phase unresolved context.
+
+    # Stored pickling error for later-phase unresolved context.
     _ctx_pickle_error: Exception | None
 
+    # Types for hook functions.
+    type UnresolvedContextHook = Callable[[pending_node, UnresolvedContext], None]
+    type ResolvedContextHook = Callable[[pending_node, ResolvedContext], None]
+    type MarkupTextHook = Callable[[pending_node, str], str]
+    type RenderedNodesHook = Callable[[pending_node, list[nodes.Node]], None]
+
+    # Hooks for processing render intermediate products.
+    _unresolved_context_hooks: list[UnresolvedContextHook]
+    _resolved_context_hooks: list[ResolvedContextHook]
+    _markup_text_hooks: list[MarkupTextHook]
+    _rendered_nodes_hooks: list[RenderedNodesHook]
+
     def __init__(
         self,
         ctx: UnresolvedContext | ResolvedContext,
@@ -50,16 +63,18 @@ def __init__(
         **attributes,
     ) -> None:
         super().__init__(rawsource, *children, **attributes)
+        self.ctx = ctx
+        self.template = tmpl
+        self.inline = inline
+        self.rendered = False
+
+        # Test whehter ctx pickle-able.
         self._ctx_pickle_error = None
         if isinstance(ctx, UnresolvedContext) and tmpl.phase != Phase.Parsing:
             try:
                 pickle.dumps(ctx)
             except Exception as exc:
                 self._ctx_pickle_error = exc
-        self.ctx = ctx
-        self.template = tmpl
-        self.inline = inline
-        self.rendered = False
 
         # Init hook lists.
         self._unresolved_context_hooks = []
@@ -239,18 +254,6 @@ def unwrap_and_replace_self_inline(self, inliner: Report.Inliner) -> None:
         # Replace self with inline nodes.
         self.replace_self(ns)
 
-    """Hooks for processing render intermediate products."""
-
-    type UnresolvedContextHook = Callable[[pending_node, UnresolvedContext], None]
-    type ResolvedContextHook = Callable[[pending_node, ResolvedContext], None]
-    type MarkupTextHook = Callable[[pending_node, str], str]
-    type RenderedNodesHook = Callable[[pending_node, list[nodes.Node]], None]
-
-    _unresolved_context_hooks: list[UnresolvedContextHook]
-    _resolved_context_hooks: list[ResolvedContextHook]
-    _markup_text_hooks: list[MarkupTextHook]
-    _rendered_nodes_hooks: list[RenderedNodesHook]
-
     def hook_unresolved_context(self, hook: UnresolvedContextHook) -> None:
         self._unresolved_context_hooks.append(hook)
 

src/sphinxnotes/render/extractx.py

@@ -41,27 +41,34 @@ def generate(self, req: ExtraContextRequest, *args, **kwargs) -> Any: ...
 # ==========================
 
 
-class _ExtraContextRegistry:
-    ctxs: dict[str, ExtraContext]
+class Registry:
+    """Registry for extra contexts."""
+
+    _ctxs: dict[str, ExtraContext]
 
     def __init__(self) -> None:
-        self.ctxs = {}
+        self._ctxs = {}
 
-    def register(self, name: str, ctx: ExtraContext) -> None:
-        if name in self.ctxs:
-            raise ValueError(f'Extra context "{name}" already registered')
-        self.ctxs[name] = ctx
+    def add(self, name: str, ctx: ExtraContext) -> None:
+        """Register an extra context.
 
-    def get(self, name: str) -> ExtraContext | None:
-        if name not in self.ctxs:
-            return None
-        return self.ctxs[name]
+        :param name: The context name, used in templates via ``load_extra('name')``
+        :param ctx: An :py:class:`ExtraContext` instance
+
+        .. note:: Using the :py:deco:`extra_context` decorator is recommended for most cases.
+        """
+        if name in self._ctxs:
+            raise ValueError(f'Extra context "{name}" already registered')
+        self._ctxs[name] = ctx
 
-    def get_names(self) -> set[str]:
-        return set(self.ctxs.keys())
 
+REGISTRY = Registry()
+"""The global registry for extra contexts.
 
-_REGISTRY = _ExtraContextRegistry()
+This is the underlying registry used by the :py:func:`extra_context` decorator.
+Using the decorator is recommended for most cases, but you can also register
+extra contexts directly via this registry.
+"""
 
 
 def extra_context(name: str):
@@ -71,19 +78,19 @@ def extra_context(name: str):
     """
 
     def decorator(cls):
-        _REGISTRY.register(name, cls())
+        REGISTRY.add(name, cls())
         return cls
 
     return decorator
 
 
 def extra_context_names() -> set[str]:
-    return _REGISTRY.get_names()
+    return set(REGISTRY._ctxs.keys())
 
 
 def extra_context_loader(request: ExtraContextRequest):
     def load_extra(name: str, *args, **kwargs) -> Any:
-        ctx = _REGISTRY.get(name)
+        ctx = REGISTRY._ctxs.get(name)
         if ctx is None:
             raise ValueError(
                 f'Extra context "{name}" is not registered. '

src/sphinxnotes/render/jinja.py

@@ -16,7 +16,6 @@
 from jinja2 import StrictUndefined, DebugUndefined
 
 from .data import ParsedData
-from .utils import Report
 
 if TYPE_CHECKING:
     from typing import Any
@@ -25,6 +24,64 @@
     from .ctx import ResolvedContext
 
 
+class Registry:
+    """Registry for customizing the Jinja2 environment.
+
+    Provides methods to add custom filters and extensions to the Jinja2
+    rendering environment used by this extension.
+
+    Usage::
+
+        from sphinxnotes.render.jinja import REGISTRY
+
+        def my_filter_factory(env):
+            def _filter(value):
+                return value.upper()
+            return _filter
+
+        REGISTRY.add_filter('my_filter', my_filter_factory)
+        REGISTRY.add_extension('jinja2.ext.i18n')
+    """
+
+    _filters: dict[str, Callable[[BuildEnvironment], Callable]]
+    _extensions: list[str]
+
+    def __init__(self) -> None:
+        self._filters = {}
+        self._extensions = []
+
+    def add_filter(
+        self, name: str, factory: Callable[[BuildEnvironment], Callable]
+    ) -> None:
+        """Register a filter factory.
+
+        :param name: The filter name, used in Jinja templates as ``{{ value|name }}``
+        :param factory: A callable that takes a :py:class:`~sphinx.environment.BuildEnvironment`
+                        and returns a filter callable
+
+        .. note:: Using the :py:deco:`filter` decorator is recommended for most cases.
+
+        """
+        if name in self._filters:
+            raise ValueError(f'Jinja filter "{name}" already registered')
+        self._filters[name] = factory
+
+    def add_extension(self, extension: str) -> None:
+        """Add a Jinja2 extension.
+
+        See `Jinja2 Extensions <https://jinja.palletsprojects.com/en/stable/extensions/>`_
+        for available builtin extensions.
+
+        :param extension: The extension module path, e.g. ``'jinja2.ext.i18n'``
+        """
+        if extension not in self._extensions:
+            self._extensions.append(extension)
+
+
+REGISTRY = Registry()
+"""The global registry for Jinja2 filter factories."""
+
+
 @dataclass
 class TemplateRenderer:
     text: str
@@ -48,10 +105,7 @@ def render(
         return self._render(ctx, debug=debug)
 
     def _render(self, ctx: dict[str, Any], debug: bool = False) -> str:
-        extensions = [
-            'jinja2.ext.loopcontrols',  # enable {% break %}, {% continue %}
-            'jinja2.ext.do',  # enable {% do ... %}
-        ]
+        extensions = list(REGISTRY._extensions)
         if debug:
             extensions.append('jinja2.ext.debug')
 
@@ -63,27 +117,19 @@ def _render(self, ctx: dict[str, Any], debug: bool = False) -> str:
 
         return env.from_string(self.text).render(ctx)
 
-    def _report_self(self, reporter: Report) -> None:
-        reporter.code(self.text, lang='jinja', caption='Template:')
-
 
 class _JinjaEnv(SandboxedEnvironment):
     _env: ClassVar[BuildEnvironment]
-    _filter_factories: ClassVar[dict[str, Callable[[BuildEnvironment], Callable]]] = {}
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
-        for name, factory in self._filter_factories.items():
+        for name, factory in REGISTRY._filters.items():
             self.filters[name] = factory(self._env)
 
     @classmethod
     def on_builder_inited(cls, app: Sphinx):
         cls._env = app.env
 
-    @classmethod
-    def add_filter(cls, name: str, factory: Callable[[BuildEnvironment], Callable]):
-        cls._filter_factories[name] = factory
-
     @override
     def is_safe_attribute(self, obj, attr, value=None):
         """
@@ -111,11 +157,14 @@ def _filter(value):
     """
 
     def decorator(ff):
-        _JinjaEnv.add_filter(name, ff)
+        REGISTRY.add_filter(name, ff)
         return ff
 
     return decorator
 
 
 def setup(app: Sphinx):
     app.connect('builder-inited', _JinjaEnv.on_builder_inited)
+
+    REGISTRY.add_extension('jinja2.ext.loopcontrols')
+    REGISTRY.add_extension('jinja2.ext.do')

src/sphinxnotes/render/markup.py

@@ -55,7 +55,10 @@ def _render(self, text: str) -> list[Node]:
                 parser = self.host.app.registry.create_source_parser(
                     self.host.app, 'rst'
                 )
-            doc = new_document(self.host.env.docname, settings=self._get_settings(parser, self.host.document))
+            doc = new_document(
+                self.host.env.docname,
+                settings=self._get_settings(parser, self.host.document),
+            )
             parser.parse(text, doc)
 
             # NOTE: Nodes produced by standalone source parser should be fixed
@@ -128,8 +131,9 @@ def _get_settings(self, parser: SphinxParser, doctree: nodes.document) -> Values
         if version_info[0] >= 9:
             try:
                 from sphinx.util.docutils import _get_settings
-                settings = _get_settings(parser,
-                    defaults=self.host.env.settings, read_config_files=True
+
+                settings = _get_settings(
+                    parser, defaults=self.host.env.settings, read_config_files=True
                 )
             except Exception as e:
                 logger.warning(