update

Author: SilverRainZ

src/sphinxnotes/render/extractx.py

@@ -5,7 +5,7 @@
 from sphinx.util.docutils import SphinxDirective, SphinxRole
 from sphinx.transforms import SphinxTransform
 
-from .render import HostWrapper
+from .render import HostWrapper, Phase
 from .ctxnodes import pending_node
 from .utils import find_current_section, Report, Reporter
 
@@ -19,46 +19,53 @@
 # ExtraContext ABC definitions
 # ============================
 
-type ExtraContext = (
-    ParsingPhaseExtraContext
-    | ParsingPhaseExtraContext
-    | ResolvingPhaseExtraContext
-    | GlobalExtraContext
-)
-"""Type alias of all available extra contexts."""
 
+class _ExtraContext(ABC):
+    """Base class of extra context."""
 
-class ParsingPhaseExtraContext(ABC):
+    phase: ClassVar[Phase | None] = None
+
+    @abstractmethod
+    def generate(self, *args, **kwargs) -> Any: ...
+
+
+class ParsingPhaseExtraContext(_ExtraContext):
     """Extra context generated during the :py:data:`~Phase.Parsing` phase.
 
     The ``generate`` method receives the current directive or role being executed.
     """
 
+    phase = Phase.Parsing
+
     @abstractmethod
     def generate(self, directive: SphinxDirective | SphinxRole) -> Any: ...
 
 
-class ParsedPhaseExtraContext(ABC):
+class ParsedPhaseExtraContext(_ExtraContext):
     """Extra context generated during the :py:data:`~Phase.Parsed` phase.
 
     The ``generate`` method receives the current Sphinx transform.
     """
 
+    phase = Phase.Parsed
+
     @abstractmethod
     def generate(self, transform: SphinxTransform) -> Any: ...
 
 
-class ResolvingPhaseExtraContext(ABC):
+class ResolvingPhaseExtraContext(_ExtraContext):
     """Extra context generated during the :py:data:`~Phase.Resolving` phase.
 
     The ``generate`` method receives the current Sphinx transform.
     """
 
+    phase = Phase.Resolving
+
     @abstractmethod
     def generate(self, transform: SphinxTransform) -> Any: ...
 
 
-class GlobalExtraContext(ABC):
+class GlobalExtraContext(_ExtraContext):
     """Extra context available in all phases.
 
     The ``generate`` method receives the Sphinx build environment.
@@ -74,42 +81,34 @@ def generate(self, env: BuildEnvironment) -> Any: ...
 
 
 class _ExtraContextRegistry:
-    ctxs: dict[str, ExtraContext]
+    ctxs: dict[str, _ExtraContext]
 
     def __init__(self) -> None:
         self.ctxs = {}
 
-    def is_extra_context(self, ctx: Any) -> bool:
-        return isinstance(
-            ctx,
-            (
-                ParsingPhaseExtraContext,
-                ParsingPhaseExtraContext,
-                ResolvingPhaseExtraContext,
-                GlobalExtraContext,
-            ),
-        )
-
-    def register(self, name: str, ctx: ExtraContext) -> None:
+    def register(self, name: str, ctx: _ExtraContext) -> None:
         if name in self.ctxs:
             raise ValueError(f'Extra context "{name}" already registered')
-        if not self.is_extra_context(ctx):
-            raise TypeError(
-                f'Invalid extra context instance "{name}", Expecting {ExtraContext}'
-            )
         self.ctxs[name] = ctx
 
-    def get(self, name: str) -> ExtraContext | None:
+    def get(self, name: str) -> _ExtraContext | None:
         if name not in self.ctxs:
             return None
         return self.ctxs[name]
 
-    def get_names_by_phase(self, cls: type) -> set[str]:
-        return {name for name, ctx in self.ctxs.items() if isinstance(ctx, cls)}
-
     def get_names(self) -> set[str]:
         return set(self.ctxs.keys())
 
+    def get_names_at_phase(self, phase: Phase | None) -> set[str]:
+        return {name for name, ctx in self.ctxs.items() if ctx.phase == phase}
+
+    def get_names_before_phase(self, phase: Phase | None) -> set[str]:
+        return {
+            name
+            for name, ctx in self.ctxs.items()
+            if phase is None or ctx.phase is None or phase >= ctx.phase
+        }
+
 
 # Global registry instance.
 _REGISTRY = _ExtraContextRegistry()
@@ -133,8 +132,8 @@ def extra_context(name: str):
 
         @extra_context('doc')
         class DocExtraContext(ParsingPhaseExtraContext):
-            def generate(self, directive):
-                return proxy(HostWrapper(directive).doctree)
+            def generate(self, ctx):
+                return proxy(HostWrapper(ctx).doctree)
 
     :param name: The context name, used in templates via ``load_extra('name')``.
     """
@@ -169,13 +168,17 @@ def __init__(self, node: pending_node) -> None:
         Reporter(node).append(self.report)
 
         # Initialize todo with requested extra contexts, validate they exist
+        total = _REGISTRY.get_names()
+        avail = _REGISTRY.get_names_before_phase(node.template.phase)
         requested = set(node.template.extra)
-        avail = _REGISTRY.get_names()
         self.todo = requested & avail
 
         # Report errors for non-existent contexts
-        if nonexist := requested - avail:
-            self.report.text(f'Extra contexts {nonexist} are not registered.')
+        if nonexist := requested - total:
+            self.report.text(f'Extra contexts {nonexist} are non-exist.')
+        if nonavail := requested - nonexist:
+            self.report.text(f'Extra contexts {nonavail} are not available '
+                             f'at pahse {node.template.phase}.')
 
     def on_anytime(self, env: BuildEnvironment) -> None:
         self._generate(GlobalExtraContext, lambda ctx: ctx.generate(env))
@@ -189,9 +192,9 @@ def on_parsed(self, transform: SphinxTransform) -> None:
     def on_resolving(self, transform: SphinxTransform) -> None:
         self._generate(ResolvingPhaseExtraContext, lambda ctx: ctx.generate(transform))
 
-    def _generate(self, cls: type, gen: Callable[..., Any]) -> None:
+    def _generate(self, cls: type[_ExtraContext], gen: Callable[..., Any]) -> None:
         # Get all context names available for this phase
-        avail = _REGISTRY.get_names_by_phase(cls)
+        avail = _REGISTRY.get_names_at_phase(cls.phase)
         # Find which ones are requested and not yet generated
         todo = avail & self.todo
 
@@ -262,17 +265,4 @@ def generate(self, env: BuildEnvironment) -> Any:
         return proxy(env)
 
 
-@extra_context('docutils')
-class DocutilsExtraContext(GlobalExtraContext):
-    @override
-    def generate(self, env: BuildEnvironment) -> Any:
-        from docutils.parsers.rst.directives import _directives
-        from docutils.parsers.rst.roles import _roles
-
-        return {
-            'directives': _directives,
-            'roles': _roles,
-        }
-
-
 def setup(app: Sphinx): ...

src/sphinxnotes/render/render.py

@@ -25,6 +25,10 @@ class Phase(Enum):
     def default(cls) -> Phase:
         return cls.Parsing
 
+    def __ge__(self, other: Phase) -> bool:
+        _ORDER = {'parsing': 1, 'parsed': 2, 'resolving': 3}
+        return _ORDER[self.value] >= _ORDER[other.value]
+
 
 @dataclass
 class Template: