feat: Provide a global Sphinx extra context

Author: SilverRainZ

src/sphinxnotes/data/config.py

@@ -17,14 +17,14 @@
 class Config:
     """Global config of extension."""
 
-    template_debug: bool
+    render_debug: bool
 
 
 def _config_inited(app: Sphinx, config: SphinxConfig) -> None:
-    Config.template_debug = config.data_template_debug
+    Config.render_debug = config.data_render_debug
 
 
 def setup(app: Sphinx):
-    app.add_config_value('data_template_debug', False, '', bool)
+    app.add_config_value('data_render_debug', False, '', bool)
 
     app.connect('config-inited', _config_inited)

src/sphinxnotes/data/render/__init__.py

@@ -42,6 +42,8 @@ def render(host: Host, pending: pending_data) -> rendered_data:
     rendered.update_all_atts(pending)
     # Copy source and line (which are not included in update_all_atts).
     rendered.source, rendered.line = pending.source, pending.line
+    # Copy the pending's children to the rendered.
+    rendered[:0] = pending.children  # TODO: do not modify?
 
     report = Report(
         'Render Debug Report', 'DEBUG', source=pending.source, line=pending.line
@@ -121,13 +123,6 @@ def replace(host: Host, pending: pending_data, rendered: rendered_data) -> None:
 
     assert pending.parent
 
-    # Clear all empty reports.
-    Reporter(pending).clear_empty()
-    # Adopt the pending's children to the rendered.
-    rendered[:0] = pending.children
-    # Clear all children.
-    pending.clear()
-
     if pending.inline:
         doc = HostWrapper(host).doctree
         # Report(nodes.system_message subclass) is not inline node,
@@ -222,7 +217,7 @@ def render_pending_node(self, pending: pending_data) -> rendered_data:
         host = cast(Host, self)
 
         # Generate and save parsing phase extra context for later use.
-        ExtraContextGenerator(pending).on_rendering(host)
+        ExtraContextGenerator(pending).on_anytime()
 
         rendered = render(host, pending)
 
@@ -318,10 +313,10 @@ def fix_lineno(level, message, *children, **kwargs):
             self.state_machine.reporter.system_message = fix_lineno
 
             # Generate and save render phase extra contexts for later use.
-            ExtraContextGenerator(pending).on_rendering(self)
+            ExtraContextGenerator(pending).on_anytime()
 
             rendered = render(self, pending)
-            replace(pending, rendered)
+            replace(self, pending, rendered)
 
         # Restore system_message method.
         self.state_machine.reporter.system_message = orig_sysmsg
@@ -409,7 +404,7 @@ def apply(self, **kwargs):
                 continue
 
             # Generate and save render phase extra contexts for later use.
-            ExtraContextGenerator(pending).on_rendering(self)
+            ExtraContextGenerator(pending).on_anytime()
 
             rendered = render(self, pending)
             replace(self, pending, rendered)
@@ -422,3 +417,7 @@ def setup(app: Sphinx) -> None:
 
     # Hook for Phase.Resolving.
     app.add_post_transform(_ResolvingHook)
+
+    from . import extractx
+
+    extractx.setup(app)

src/sphinxnotes/data/render/extractx.py

@@ -6,10 +6,11 @@
 
 from ..utils import find_current_section
 from ..utils.ctxproxy import proxy
-from .renderer import Host, ParseHost
 
 if TYPE_CHECKING:
     from typing import Any, Callable, ClassVar
+    from sphinx.application import Sphinx
+    from .renderer import ParseHost
 
 
 from ..utils import Report
@@ -18,23 +19,17 @@
 from .reporter import Reporter
 
 
-class ExtraContxt(ABC):
-    """Base class for extra context generator in different render phase."""
-
-    ...
-
-
-class RenderPhaseExtraContext(ExtraContxt):
+class GlobalExtraContxt(ABC):
     @abstractmethod
-    def generate(self, host: Host) -> Any: ...
+    def generate(self) -> Any: ...
 
 
-class ParsePhaseExtraContext(ExtraContxt):
+class ParsePhaseExtraContext(ABC):
     @abstractmethod
     def generate(self, host: ParseHost) -> Any: ...
 
 
-class TransformPhaseExtraContext(ExtraContxt):
+class TransformPhaseExtraContext(ABC):
     @abstractmethod
     def generate(self, host: TransformHost) -> Any: ...
 
@@ -49,50 +44,47 @@ class ExtraContextRegistry:
     parsing: dict[str, ParsePhaseExtraContext]
     parsed: dict[str, ParsePhaseExtraContext]
     post_transform: dict[str, TransformPhaseExtraContext]
-    render: dict[str, RenderPhaseExtraContext]
+    global_: dict[str, GlobalExtraContxt]
 
     def __init__(self) -> None:
         self.names = set()
         self.parsing = {}
         self.parsed = {}
         self.post_transform = {}
-        self.render = {}
+        self.global_ = {}
 
-        self.add_parsing_phase_extra_context('markup', _MarkupExtraContext())
-        self.add_parsing_phase_extra_context('section', _SectionExtraContext())
-        self.add_render_phase_extra_context('doc', _DocExtraContext())
-        self.add_render_phase_extra_context('env', _SphinxEnvExtraContext())
-        self.add_render_phase_extra_context('config', _SphinxConfigExtraContext())
+        self.add_global_context('sphinx', _SphinxExtraContext())
+        self.add_parsing_phase_context('markup', _MarkupExtraContext())
+        self.add_parsing_phase_context('section', _SectionExtraContext())
+        self.add_parsing_phase_context('doc', _DocExtraContext())
 
     def _name_dedup(self, name: str) -> None:
         # TODO: allow dup
         if name in self.names:
             raise ValueError(f'Context generator {name} already exists')
         self.names.add(name)
 
-    def add_parsing_phase_extra_context(
+    def add_parsing_phase_context(
         self, name: str, ctxgen: ParsePhaseExtraContext
     ) -> None:
         self._name_dedup(name)
         self.parsing['_' + name] = ctxgen
 
-    def add_parsed_phase_extra_context(
+    def add_parsed_phase_context(
         self, name: str, ctxgen: ParsePhaseExtraContext
     ) -> None:
         self._name_dedup(name)
         self.parsed['_' + name] = ctxgen
 
-    def add_post_transform_phase_extra_context(
+    def add_post_transform_phase_context(
         self, name: str, ctxgen: TransformPhaseExtraContext
     ) -> None:
         self._name_dedup(name)
         self.post_transform['_' + name] = ctxgen
 
-    def add_render_phase_extra_context(
-        self, name: str, ctxgen: RenderPhaseExtraContext
-    ):
+    def add_global_context(self, name: str, ctxgen: GlobalExtraContxt):
         self._name_dedup(name)
-        self.render['_' + name] = ctxgen
+        self.global_['_' + name] = ctxgen
 
 
 # ===================================
@@ -112,9 +104,9 @@ def generate(self, host: ParseHost) -> Any:
         }
 
 
-class _DocExtraContext(RenderPhaseExtraContext):
+class _DocExtraContext(ParsePhaseExtraContext):
     @override
-    def generate(self, host: Host) -> Any:
+    def generate(self, host: ParseHost) -> Any:
         return proxy(HostWrapper(host).doctree)
 
 
@@ -125,16 +117,12 @@ def generate(self, host: ParseHost) -> Any:
         return proxy(find_current_section(parent))
 
 
-class _SphinxEnvExtraContext(RenderPhaseExtraContext):
-    @override
-    def generate(self, host: Host) -> Any:
-        return proxy(host.env)
+class _SphinxExtraContext(GlobalExtraContxt):
+    app: ClassVar[Sphinx]
 
-
-class _SphinxConfigExtraContext(RenderPhaseExtraContext):
     @override
-    def generate(self, host: Host) -> Any:
-        return proxy(host.config)
+    def generate(self) -> Any:
+        return proxy(self.app)
 
 
 # ========================
@@ -150,12 +138,17 @@ class ExtraContextGenerator:
 
     def __init__(self, node: pending_data) -> None:
         self.node = node
-        self.report = Report('Extra Context Generation Report', 'ERROR')
+        self.report = Report(
+            'Extra Context Generation Report',
+            'ERROR',
+            source=node.source,
+            line=node.line,
+        )
         Reporter(node).append(self.report)
 
-    def on_rendering(self, host: Host) -> None:
-        for name, ctxgen in self.registry.render.items():
-            self._safegen(name, lambda: ctxgen.generate(host))
+    def on_anytime(self) -> None:
+        for name, ctxgen in self.registry.global_.items():
+            self._safegen(name, lambda: ctxgen.generate())
 
     def on_parsing(self, host: ParseHost) -> None:
         for name, ctxgen in self.registry.parsing.items():
@@ -174,5 +167,9 @@ def _safegen(self, name: str, gen: Callable[[], Any]):
             # ctxgen.generate can be user-defined code, exception of any kind are possible.
             self.node.extra[name] = gen()
         except Exception:
-            self.report.text(f'Failed to generate extra context {name}:')
+            self.report.text(f'Failed to generate extra context "{name}":')
             self.report.excption()
+
+
+def setup(app: Sphinx):
+    _SphinxExtraContext.app = app

src/sphinxnotes/data/render/reporter.py

@@ -2,7 +2,6 @@
 from dataclasses import dataclass
 from typing import Callable
 
-from docutils.nodes import system_message
 
 from ..utils import Report
 from .nodes import pending_data, rendered_data
@@ -33,7 +32,3 @@ def clear(self, pred: Callable[[Report], bool] | None = None) -> list[Report]:
 
     def clear_empty(self) -> None:
         self.clear(lambda x: x.empty())
-
-    @staticmethod
-    def reports_to_system_messages(reports: list[Report]) -> list[system_message]:
-        return [x for x in reports]

src/sphinxnotes/data/utils/__init__.py

@@ -104,7 +104,6 @@ def __init__(
         self, title: str, level: Level = 'DEBUG', *children, **attributes
     ) -> None:
         super().__init__(title + ':', type=level, level=2, *children, **attributes)
-        self.log(title)
 
     def empty(self) -> bool:
         # title is the only children
@@ -142,8 +141,8 @@ def list(self, lines: Iterable[str]) -> None:
         self.node(bullet_list)
 
     def excption(self) -> None:
-        self.text('Exception:')
-        self.code(traceback.format_exc())
+        # https://pygments.org/docs/lexers/#pygments.lexers.python.PythonTracebackLexer
+        self.code(traceback.format_exc(), lang='pytb')
 
     def is_error(self) -> bool:
         return self.level == 'ERROR'