update

Author: SilverRainZ

docs/index.rst

@@ -8,7 +8,7 @@ sphinxnotes-data
 FooBar
 ======
 
-.. data:autodef::
+.. data:auto::
    :color:
    :size: 1
 

src/sphinxnotes/data/__init__.py

@@ -7,7 +7,8 @@
 """
 
 from __future__ import annotations
-from typing import cast
+from typing import cast, override
+from abc import abstractmethod
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -41,7 +42,8 @@ def render(
         self, caller: SphinxDirective | SphinxTransform, replace: bool = False
     ) -> rendered_data_node:
         if self.need_external_data:
-            self._complete_external_data()
+            parent = self.parent or caller.state.parent
+            self._complete_external_data(parent)
 
         try:
             parsed = self.schema.parse(self.data)
@@ -71,20 +73,23 @@ def render(
 
         return rendered
 
-    def _complete_external_data(self):
+    def _complete_external_data(self, parent: nodes.Element):
+        # NOTE: Do not use self.parent here, the pending_data_node may be just
+        # created and haven't inserted to doctree.
         if not self.data.name:
-            if title := find_titular_node_upward(self.parent):
+            if title := find_titular_node_upward(parent):
                 self.data.name = title.astext()
 
-        if not self.data.content and self.parent:
+        if not self.data.content:
             contnodes = []
-            for i, child in enumerate(self.parent):
+            for i, child in enumerate(parent):
                 if child == self:
                     contnodes = self.parent[i:]
             self.data.content = '\n\n'.join([n.astext() for n in contnodes])
 
 
-class rendered_data_node(DataNode, nodes.container): ...
+class rendered_data_node(DataNode, nodes.container):
+    anchor: nodes.Element | None
 
 
 class TemplateDirective(SphinxDirective):
@@ -104,7 +109,7 @@ def run(self) -> list[nodes.Node]:
         return []
 
 
-class DataSchemaDirective(FreeStyleDirective):
+class SchemaDirective(FreeStyleDirective):
     optional_arguments = 1
     option_spec = FreeStyleOptionSpec()
     has_content = True
@@ -121,52 +126,134 @@ def run(self) -> list[nodes.Node]:
         return []
 
 
-class DefineDirective(SphinxDirective):
-    optional_arguments = 1
-    has_content = True
+class BaseDataDirective(SphinxDirective):
+
+    """Methods to be overrided."""
+
+    @abstractmethod
+    def current_template(self) -> Template: ...
+
+    @abstractmethod
+    def current_schema(self) -> Schema: ...
+
+    def process_data(self, data: Data) -> None: ...
+
+    def process_pending_node(self, n: pending_data_node) -> None: ...
+
+    def process_rendered_node(self, n: rendered_data_node) -> None: ...
+
+    def run(self) -> list[nodes.Node]:
+        pending = self.build_pending_node()
+        if pending.template.phase != Phase.Parsing:
+            return [pending}
+        return [self.render_pending_node(pending)]
+
+    """Methods used internal."""
 
-    def _extract_data(self) -> Data:
-        return Data(
+    def build_pending_node(self) -> pending_data_node:
+        data = Data(
             self.arguments[0] if self.arguments else None,
             self.options.copy(),
             '\n'.join(self.content) if self.has_content else None,
         )
+        self.process_data(data)
+
+        tmpl = self.current_template()
+        schema = self.current_schema()
+
+        n = pending_data_node()
+        self.set_source_info(n)
+        n.data, n.template, n.schema = data, tmpl, schema
+        self.process_pending_node(n)
+
+        return n
+
+    def render_pending_node(self, pending: pending_data_node) -> rendered_data_node:
+         rendered = pending.render(self)
+         self.process_rendered_node(rendered)
+         return rendered
+
 
+class FreeDataDirective(BaseDataDirective, FreeStyleDirective):
+    optional_arguments = 1
+    has_content = True
+
+    @override
     def current_template(self) -> Template:
         tmpl = self.env.current_document.get(TEMPLATE_KEY, Template.default())
         return cast(Template, tmpl)
 
+    @override
     def current_schema(self) -> Schema:
         schema = self.env.current_document.get(SCHEMA_KEY, Schema.default())
         return cast(Schema, schema)
 
-    def new_pending_node(self) -> pending_data_node:
-        data = self._extract_data()
-        tmpl = self.current_template()
-        schema = self.current_schema()
 
-        n = pending_data_node()
-        self.set_source_info(n)
-        n.data, n.template, n.schema = data, tmpl, schema
+class AutoDataDirective(FreeDataDirective):
+    @override
+    def process_pending_node(self, n: pending_data_node) -> None:
+        n.need_external_data = True
 
-        return n
 
-    def run(self) -> list[nodes.Node]:
-        n = self.new_pending_node()
-        if n.template.phase != Phase.Parsing:
-            return [n]
+class FixedDataDirective(BaseDataDirective):
+    final_argument_whitespace = True
 
-        return [n.render(self)]
+    schema: Schema
+    template: Template
 
+    @classmethod
+    def derive(cls, name: str, tmpl: Template, schema: Schema) -> type[FixedDataDirective]:
+        """Generate an AnyDirective child class for describing object."""
+        base_classes = []
+        base_classes.append(FixedDataDirective)
+
+        if not schema.name:
+            required_arguments = 0
+            optional_arguments = 0
+        elif schema.name.required:
+            required_arguments = 1
+            optional_arguments = 0
+        else:
+            required_arguments = 0
+            optional_arguments = 1
 
-class FreeDefineDirective(DefineDirective, FreeStyleDirective): ...
+        if isinstance(schema.attrs, Field):
+            base_classes.append(FreeStyleDirective)
+            if schema.attrs.required:
+                option_spec = FreeStyleOptionSpec(directives.unchanged_required)
+            else:
+                option_spec = FreeStyleOptionSpec(directives.unchanged)
+        else:
+            option_spec = {}
+            for name, field in schema.attrs.items():
+                if field.required:
+                    option_spec[name] = directives.unchanged_required
+                else:
+                    option_spec[name] = directives.unchanged
+
+        has_content = schema.content is not None
+
+        # Generate directive class
+        return type(
+            'Any%sDirective' % name.title(),
+            tuple(base_classes),
+            {
+                'schema': schema,
+                'template': tmpl,
+                'has_content': has_content,
+                'required_arguments': required_arguments,
+                'optional_arguments': optional_arguments,
+                'option_spec': option_spec,
+            },
+        )
 
+    @override
+    def current_template(self) -> Template:
+        return self.template
 
-class AutoDefineDirective(DefineDirective, FreeStyleDirective):
-    def new_pending_node(self) -> pending_data_node:
-        n = super().new_pending_node()
-        n.need_external_data = True
-        return n
+    @override
+    def current_schema(self) -> Schema:
+        return self.schema
 
 
 class ParsedHook(SphinxDirective):
@@ -210,16 +297,17 @@ def apply(self, **kwargs):
             if pending.template.phase != Phase.Resolving:
                 continue
 
+            # TODO: deal with ValueError
             pending.render(self, replace=True)
 
 
 def setup(app: Sphinx):
     meta.pre_setup(app)
 
     app.add_directive('data:tmpl', TemplateDirective, False)
-    app.add_directive('data:schema', DataSchemaDirective, False)
-    app.add_directive('data:def', FreeDefineDirective, False)
-    app.add_directive('data:autodef', AutoDefineDirective, False)
+    app.add_directive('data:schema', SchemaDirective, False)
+    app.add_directive('data:def', FreeDataDirective, False)
+    app.add_directive('data:auto', AutoDataDirective, False)
     app.add_directive('data:parsed-hook', ParsedHook, False)
 
     app.connect('source-read', on_source_read)

src/sphinxnotes/data/context_proxy.py

@@ -4,10 +4,12 @@
 from types import MappingProxyType
 
 from docutils import nodes
-
 from sphinx.util import logging
 from sphinx.config import Config as SphinxConfig
 
+from .utils import find_first_child
+
+
 logger = logging.getLogger(__name__)
 
 
@@ -98,7 +100,7 @@ def __str__(self) -> str:
 class NodeWithTitle(Node):
     @proxy_property
     def title(self) -> Node | None:
-        return self._obj.next_node(nodes.Titular)
+        return find_first_child(self._obj, nodes.Titular) # type: ignore
 
 
 @dataclass(frozen=True)
@@ -128,7 +130,7 @@ def sections(self) -> tuple[Section, ...]:
 
 
 @dataclass(frozen=True)
-class ConfigProxy(Proxy):
+class Config(Proxy):
     _obj: SphinxConfig
 
 
@@ -139,7 +141,7 @@ class ConfigProxy(Proxy):
 SPECIFIC_TYPE_REGISTRY: dict[type, type[Proxy]] = {
     nodes.document: Document,
     nodes.section: Section,
-    SphinxConfig: ConfigProxy,
+    SphinxConfig: Config,
 }