refactor: Load extra context on demand

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.py

@@ -110,6 +110,10 @@
 }
 
 extensions.append('sphinxnotes.project')
+
+import sphinxnotes.project.sphinxnotes_render_ext as project_render_ext
+for name in ('autoconfval', 'autoobj'):
+    project_render_ext.DATA_DEFINE_DIRECTIVES[name]['template'].pop('extra', None)
 primary_domain = 'any'
 
 # -- Eat your own dog food --------------------------------------------------

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,7 +199,6 @@ The following extra contexts are available:
       :style: grid
 
       .. data.render::
-         :extra: env
 
          {% set env = load_extra('env') %}
 
@@ -224,7 +215,6 @@ The following extra contexts are available:
       :style: grid
 
       .. data.render::
-         :extra: markup
 
          {%
          set m = load_extra('markup')
@@ -247,7 +237,6 @@ The following extra contexts are available:
       :style: grid
 
       .. data.render::
-         :extra: section
 
           Section Title:
          "{{ load_extra('section').title }}"
@@ -261,7 +250,6 @@ The following extra contexts are available:
       :style: grid
 
       .. data.render::
-         :extra: doc
 
          Document title:
          "{{ load_extra('doc').title }}".
@@ -331,7 +319,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 +341,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 +364,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 ExtraContextGenerator
 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
     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,7 +58,6 @@ 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
@@ -131,14 +129,19 @@ def err_report() -> Report:
 
         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')
 
         # 2. Render the template and context to markup text.
         try:
-            markup = TemplateRenderer(self.template.text).render(ctx, extra=self.extra)
+            extras = ExtraContextGenerator(self, host)
+            report.text('Available extra context (just keys):')
+            report.code(pformat(sorted(extras.names())), lang='python')
+            markup = TemplateRenderer(self.template.text).render(
+                ctx,
+                load_extra=extras.load,
+                extra_names=sorted(extras.names()),
+            )
         except Exception as e:
             report = err_report()
             report.text('Failed to render Jinja template:')

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