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,21 @@ See :doc:`tmpl` for built-in extra-context names such as ``doc`` and
    :members:
    :undoc-members:
 
+.. autoclass:: sphinxnotes.render.ExtraContextRegistry
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :class-doc-from: both
+
 Filters
 =======
 
 .. autodecorator:: sphinxnotes.render.filter
 
+.. autoclass:: sphinxnotes.render.JinjaRegistry
+   :members:
+   :undoc-members:
+
 Data, Field and Schema
 ======================
 
@@ -131,11 +141,9 @@ Data, Field and Schema
    :members: name, attrs, content
    :undoc-members:
 
-.. autoclass:: sphinxnotes.render.data.Registry
+.. autoclass:: sphinxnotes.render.DataRegistry
    :members:
 
-   .. autotype:: sphinxnotes.render.data.ByOptionStore
-
 Registry
 ========
 
@@ -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

@@ -11,7 +11,7 @@
 
 from . import meta
 from .data import (
-    Registry as DataRegistry,
+    DataRegistry,
     REGISTRY as DATA_REGISTRY,
     PlainValue,
     Value,
@@ -28,6 +28,8 @@
     extra_context,
     ExtraContext,
     ExtraContextRequest,
+    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, 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/data.py

@@ -106,7 +106,7 @@ def _str_conv(v: str) -> str:
     return vv if isinstance(vv, str) else v
 
 
-class Registry:
+class DataRegistry:
     """Stores supported element types and element forms (containers)."""
 
     etypes: dict[str, type]
@@ -227,7 +227,7 @@ def add_by_option(
                      in the DSL
         :param etype: The value type for this option
         :param default: The default value for this option
-        :param store: How to store multiple values
+        :param store: How to store multiple values, can be ``'assign'`` or ``'append'``
         :param aliases: Alternative names for this option
 
         .. seealso:: :ref:`add-custom-by-options`
@@ -239,7 +239,7 @@ def add_by_option(
             self.byopts[alias] = opt
 
 
-REGISTRY = Registry()
+REGISTRY = DataRegistry()
 
 # ======================
 # Data, Field and Schema

src/sphinxnotes/render/extractx.py

@@ -41,27 +41,34 @@ def generate(self, req: ExtraContextRequest, *args, **kwargs) -> Any: ...
 # ==========================
 
 
-class _ExtraContextRegistry:
-    ctxs: dict[str, ExtraContext]
+class ExtraContextRegistry:
+    """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 = ExtraContextRegistry()
+"""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. '