refactor: Load extra context on demand (#12)

* refactor: Load extra context on demand

* refactor: Inject template globals explicitly

* chore

* refactor: Replace extra context loader with closure

* docs: Clarify ExtraContextRequest.host

* update

* refactor: Shorten extra context request args

* chore: make fmt

* refactor: Restrict section extra context phases

* docs: Minor docs changes

Author: SilverRainZ

docs/api.rst

@@ -92,24 +92,16 @@ Extra Context
 =============
 
 See :doc:`tmpl` for built-in extra-context names such as ``doc`` and
-``sphinx``, plus usage examples.
+``env``, plus usage examples.
 
 .. autodecorator:: sphinxnotes.render.extra_context
 
-.. autoclass:: sphinxnotes.render.ParsingPhaseExtraContext
-   :members: phase, generate
+.. autoclass:: sphinxnotes.render.ExtraContext
+   :members: generate
    :undoc-members:
 
-.. autoclass:: sphinxnotes.render.ParsedPhaseExtraContext
-   :members: phase, generate
-   :undoc-members:
-
-.. autoclass:: sphinxnotes.render.ResolvingPhaseExtraContext
-   :members: phase, generate
-   :undoc-members:
-
-.. autoclass:: sphinxnotes.render.GlobalExtraContext
-   :members: phase, generate
+.. autoclass:: sphinxnotes.render.ExtraContextRequest
+   :members:
    :undoc-members:
 
 Filters

docs/conf.rst

@@ -25,7 +25,5 @@ The extension provides the following configuration:
      - ``text`` (str): the Jinja2 template text.
      - ``on`` (str, optional): same as :rst:dir:`data.template:on`
      - ``debug`` (bool, optional): same as :rst:dir:`data.template:debug`
-     - ``extra`` (list[str], optional): same as :rst:dir:`data.template:extra`
 
    See :ref:`usage-custom-directive` for example.
-

docs/ext.rst

@@ -69,11 +69,8 @@ Extending Extra Contexts
 Extra contexts are registered by a
 :py:deco:`sphinxnotes.render.extra_context` class decorator.
 
-The decorated class must be one of the following classes:
-:py:class:`~sphinxnotes.render.ParsingPhaseExtraContext`,
-:py:class:`~sphinxnotes.render.ParsedPhaseExtraContext`,
-:py:class:`~sphinxnotes.render.ResolvingPhaseExtraContext`,
-:py:class:`~sphinxnotes.render.GlobalExtraContext`.
+The decorated class must be a subclass of
+:py:class:`~sphinxnotes.render.ExtraContext`.
 
 .. literalinclude:: ../tests/roots/test-extra-context/conf.py
    :language: python
@@ -88,7 +85,6 @@ The decorated class must be one of the following classes:
    :style: grid
 
    .. data.render::
-      :extra: cat
 
       {{ load_extra('cat').name }}
 

docs/tmpl.rst

@@ -158,20 +158,13 @@ sources (such as Sphinx application, JSON file, and etc.). Unlike main context
 which comes from the directive/role itself, extra context lets you fetch data
 that was prepared beforehand.
 
-Extra contexts are typically generated on demand at different construction stages,
-so you need to declare them in advance, and load it in the template using the
-``load_extra()`` function:
-
-The way of declaring extra context is vary depending on the extension you use.
-For ``sphinxnotes.render.ext`` extension, :rst:dir:`data.template:extra`,
-:rst:dir:`data.render:extra` and the ``templat.extra`` field of
-:confval:`render_ext_data_define_directives` are for this.
+Extra contexts are generated on demand. Load them in the template using the
+``load_extra()`` function.
 
 .. example::
    :style: grid
 
    .. data.render::
-      :extra: doc
 
       {% set doc = load_extra('doc') %}
 
@@ -191,7 +184,6 @@ The following extra contexts are available:
       :style: grid
 
       .. data.render::
-         :extra: app
 
          {% set app = load_extra('app') %}
 
@@ -207,15 +199,14 @@ The following extra contexts are available:
       :style: grid
 
       .. data.render::
-         :extra: env
 
          {% set env = load_extra('env') %}
 
          **{{ env.all_docs | length }}**
          documents found.
 
 ``markup``
-   :Phase: parsing and later
+   :Phase: :term:`parsing`
 
    Information about the current directive or role invocation, such as its
    type, name, source text, and line number.
@@ -224,7 +215,6 @@ The following extra contexts are available:
       :style: grid
 
       .. data.render::
-         :extra: markup
 
          {%
          set m = load_extra('markup')
@@ -238,30 +228,29 @@ The following extra contexts are available:
             {% endfor %}
  
 ``section``
-   :Phase: parsing and later
+   :Phase: :term:`parsed` and :term:`resolving`
 
    A proxy to the current :py:class:`docutils.nodes.section` node, when one
-   exists.
+   exists. This extra context is not available during the parsing phase.
 
    .. example::
       :style: grid
 
       .. data.render::
-         :extra: section
+         :on: parsed
 
-          Section Title:
+         Section Title:
          "{{ load_extra('section').title }}"
 
 ``doc``
-   :Phase: parsing and later
+   :Phase: all
 
    A proxy to the current :py:class:`docutils.notes.document` node.
 
    .. example::
       :style: grid
 
       .. data.render::
-         :extra: doc
 
          Document title:
          "{{ load_extra('doc').title }}".
@@ -331,7 +320,6 @@ Each template has a render phase that determines when it is processed:
 
          .. data.render::
             :on: parsing
-            :extra: doc env
 
             {% set doc = load_extra('doc') %}
             {% set env = load_extra('env') %}
@@ -354,7 +342,6 @@ Each template has a render phase that determines when it is processed:
 
          .. data.render::
             :on: parsed
-            :extra: doc env
 
             {% set doc = load_extra('doc') %}
             {% set env = load_extra('env') %}
@@ -378,7 +365,6 @@ Each template has a render phase that determines when it is processed:
 
          .. data.render::
             :on: resolving
-            :extra: doc env
 
             {% set doc = load_extra('doc') %}
             {% set env = load_extra('env') %}

docs/usage.rst

@@ -57,11 +57,6 @@ Directives
 
       Enable :ref:`debug report <debug>` for template rendering.
 
-   .. rst:directive:option:: extra
-      :type: space separted list
-
-      List of :ref:`extra-context` to be used in the template.
-
    The content of the directive should be Jinja2 Template, please refer to
    ::doc:`tmpl`.
 
@@ -116,7 +111,6 @@ Directives
 
    .. rst:directive:option:: on
    .. rst:directive:option:: debug
-   .. rst:directive:option:: extra
 
       The options of this directive are same to :rst:dir:`data.template`.
 

src/sphinxnotes/render/__init__.py

@@ -26,10 +26,8 @@
 from .ctxnodes import pending_node
 from .extractx import (
     extra_context,
-    ParsingPhaseExtraContext,
-    ParsedPhaseExtraContext,
-    ResolvingPhaseExtraContext,
-    GlobalExtraContext,
+    ExtraContext,
+    ExtraContextRequest,
 )
 from .pipeline import BaseContextRole, BaseContextDirective
 from .sources import (
@@ -58,10 +56,8 @@
     'Template',
     'UnresolvedContext',
     'ResolvedContext',
-    'ParsingPhaseExtraContext',
-    'ParsedPhaseExtraContext',
-    'ResolvingPhaseExtraContext',
-    'GlobalExtraContext',
+    'ExtraContext',
+    'ExtraContextRequest',
     'extra_context',
     'pending_node',
     'BaseContextRole',

src/sphinxnotes/render/ctxnodes.py

@@ -12,6 +12,7 @@
     UnresolvedContext,
     ResolvedContext,
 )
+from .extractx import ExtraContextRequest, extra_context_loader, extra_context_names
 from .markup import MarkupRenderer
 from .jinja import TemplateRenderer
 from .utils import (
@@ -21,7 +22,7 @@
 )
 
 if TYPE_CHECKING:
-    from typing import Any, Callable
+    from typing import Callable, Any
     from .markup import Host
     from .ctx import ResolvedContext
 
@@ -31,8 +32,6 @@ class pending_node(nodes.Element):
 
     # The context to be rendered by Jinja template.
     ctx: UnresolvedContext | ResolvedContext
-    # The extra context as supplement to ctx.
-    extra: dict[str, Any]
     #: Jinja template for rendering the context.
     template: Template
     #: Whether rendering to inline nodes.
@@ -59,14 +58,13 @@ def __init__(
             except Exception as exc:
                 self._ctx_pickle_error = exc
         self.ctx = ctx
-        self.extra = {}
         self.template = tmpl
         self.inline = inline
         self.rendered = False
 
         # Init hook lists.
         self._unresolved_context_hooks = []
-        self._resolved_data_hooks = []
+        self._resolved_context_hooks = []
         self._markup_text_hooks = []
         self._rendered_nodes_hooks = []
 
@@ -126,19 +124,25 @@ def err_report() -> Report:
         else:
             ctx = self.ctx
 
-        for hook in self._resolved_data_hooks:
+        for hook in self._resolved_context_hooks:
             hook(self, ctx)
 
         report.text(f'Resolved context (type: {type(ctx)}):')
         report.code(pformat(ctx), lang='python')
-        report.text('Extra context (only keys):')
-        report.code(pformat(list(self.extra.keys())), lang='python')
         report.text(f'Template (phase: {self.template.phase}):')
         report.code(self.template.text, lang='jinja')
 
+        extractx_req = ExtraContextRequest(self.template.phase, self, host.env, host)
+        report.text('Available extra context names:')
+        report.code(pformat(sorted(extra_context_names())), lang='python')
+
         # 2. Render the template and context to markup text.
         try:
-            markup = TemplateRenderer(self.template.text).render(ctx, extra=self.extra)
+            markup = TemplateRenderer(self.template.text).render(
+                ctx,
+                globals={'load_extra': extra_context_loader(extractx_req)},
+                debug=self.template.debug,
+            )
         except Exception as e:
             report = err_report()
             report.text('Failed to render Jinja template:')
@@ -227,15 +231,15 @@ def unwrap_and_replace_self_inline(self, inliner: Report.Inliner) -> None:
     type RenderedNodesHook = Callable[[pending_node, list[nodes.Node]], None]
 
     _unresolved_context_hooks: list[UnresolvedContextHook]
-    _resolved_data_hooks: list[ResolvedContextHook]
+    _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)
 
     def hook_resolved_context(self, hook: ResolvedContextHook) -> None:
-        self._resolved_data_hooks.append(hook)
+        self._resolved_context_hooks.append(hook)
 
     def hook_markup_text(self, hook: MarkupTextHook) -> None:
         self._markup_text_hooks.append(hook)

src/sphinxnotes/render/ext/adhoc.py

@@ -50,19 +50,15 @@ class TemplateDefineDirective(SphinxDirective):
     option_spec = {
         'on': phase_option_spec,
         'debug': directives.flag,
-        'extra': directives.unchanged,
     }
     has_content = True
 
     @override
     def run(self) -> list[nodes.Node]:
-        extra = self.options.get('extra', '')
-
         self.env.temp_data[TEMPLATE_KEY] = Template(
             '\n'.join(self.content),
             phase=self.options.get('on', Phase.default()),
             debug='debug' in self.options,
-            extra=extra.split() if extra else [],
         )
 
         return []
@@ -135,7 +131,6 @@ class DataRenderDirective(BaseContextDirective):
     option_spec = {
         'on': phase_option_spec,
         'debug': directives.flag,
-        'extra': directives.unchanged,
     }
     has_content = True
 
@@ -145,14 +140,10 @@ def current_context(self) -> UnresolvedContext | ResolvedContext:
 
     @override
     def current_template(self) -> Template:
-        extra_str = self.options.get('extra', '')
-        extra_list = extra_str.split() if extra_str else []
-
         return Template(
             '\n'.join(self.content),
             phase=self.options.get('on', Phase.default()),
             debug='debug' in self.options,
-            extra=extra_list,
         )
 
 

src/sphinxnotes/render/ext/derive.py

@@ -31,7 +31,6 @@
             Optional('on', default='parsing'): Or('parsing', 'parsed', 'resolving'),
             'text': str,
             Optional('debug', default=False): bool,
-            Optional('extra', default=[]): list,
         },
     }
 )
@@ -50,7 +49,6 @@ def _validate_directive_define(d: dict, config: Config) -> tuple[Schema, Templat
         text=tmpldef['text'],
         phase=Phase[tmpldef['on'].title()],
         debug=tmpldef['debug'],
-        extra=tmpldef['extra'],
     )
 
     return schema, template