Merge pull request #53 from sphinx-notes/auto

Impl ``AutoObjDefineDirective``

Author: SilverRainZ

docs/conf.py

@@ -173,5 +173,3 @@
 }
 
 primary_domain = obj_domain_name
-
-data_template_debug = True

docs/conf.rst

@@ -9,3 +9,5 @@ The extension provides the following configuration:
 .. autoconfval:: obj_type_defines
 
 .. autoconfval:: obj_domain_dump
+
+.. autoconfval:: obj_auto_obj

src/sphinxnotes/any/__init__.py

@@ -13,12 +13,12 @@
 
 from sphinx.errors import ConfigError
 from sphinx.util import logging
-from sphinxnotes.data import Schema, Config as DataConfig
+from sphinxnotes.data import Schema
 
 from schema import Schema as DictSchema, SchemaError as DictSchemaError, Optional, Or
 
 from . import meta
-from .obj import Templates
+from .obj import Templates, ObjTypeDef
 from .domain import ObjDomain
 
 if TYPE_CHECKING:
@@ -40,11 +40,13 @@
             Optional('ref', default='{{ name }}'): str,
             Optional('ref_by', default={}): {str: str},
         },
+        Optional('auto', default=False): bool,
+        Optional('debug', default=False): bool,
     }
 )
 
 
-def _validate_objtype_defines_dict(d: dict) -> tuple[Schema, Templates]:
+def _validate_objtype_defines_dict(d: dict, config: Config) -> ObjTypeDef:
     objdef = OBJTYPE_DEFINE.validate(d)
 
     schemadef = objdef['schema']
@@ -58,10 +60,12 @@ def _validate_objtype_defines_dict(d: dict) -> tuple[Schema, Templates]:
         tmplsdef['header'],
         tmplsdef['ref'],
         tmplsdef['ref_by'],
-        debug=DataConfig.render_debug,
+        debug=objdef['debug'],
     )
 
-    return schema, tmpls
+    auto = objdef['auto'] or config.obj_auto_obj
+
+    return ObjTypeDef(schema=schema, templates=tmpls, auto=auto)
 
 
 def _config_inited(app: Sphinx, config: Config) -> None:
@@ -70,10 +74,12 @@ def _config_inited(app: Sphinx, config: Config) -> None:
     for objtype, objdef in app.config.obj_type_defines.items():
         # TODO: check ":" in objtype to support multiple domain
         try:
-            schema, tmpls = _validate_objtype_defines_dict(objdef)
+            objtypedef = _validate_objtype_defines_dict(objdef, config)
         except (DictSchemaError, ValueError) as e:
-            raise ConfigError(f'Validating obj_type_defines[{repr(objtype)}]: {e}') from e
-        ObjDomain.add_objtype(objtype, schema, tmpls)
+            raise ConfigError(
+                f'Validating obj_type_defines[{repr(objtype)}]: {e}'
+            ) from e
+        ObjDomain.add_objtype(objtype, objtypedef)
 
     app.add_domain(ObjDomain)
 
@@ -97,6 +103,7 @@ def setup(app: Sphinx):
         'The ``objdef`` vaule is also a ``dict``, '
         'please refer to :ref:`writing-objdef` for more details.',
     )
+    app.add_config_value('obj_auto_obj', True, 'env', types=bool)
 
     app.connect('config-inited', _config_inited)
 

src/sphinxnotes/any/domain.py

@@ -12,6 +12,8 @@
 from typing import TYPE_CHECKING, override, cast, TypeVar
 from pprint import pformat
 
+from sphinxnotes.data.data import PendingData
+
 from .indexers import LiteralIndexer, PathIndexer, YearIndexer, MonthIndexer
 
 from docutils import nodes
@@ -23,18 +25,25 @@
 from sphinx.errors import ExtensionError
 from sphinxnotes.data import (
     PlainValue,
+    RawData,
+    Template,
     ValueWrapper,
     ParsedData,
     Schema,
     pending_node,
-    rendered_node,
     StrictDataDefineDirective,
 )
-from sphinxnotes.data.utils import Report, find_nearest_block_element, find_parent
+from sphinxnotes.data.utils import (
+    Report,
+    find_nearest_block_element,
+    find_parent,
+    find_titular_node_upward,
+)
 
 from .obj import (
     Object,
     RefType,
+    ObjTypeDef,
     Templates,
     Category,
     Indexer,
@@ -163,14 +172,26 @@ def get_objects(self) -> Iterator[tuple[str, str, str, str, str, int]]:
     """Publish methods."""
 
     @classmethod
-    def add_objtype(cls, objtype: str, schema: Schema, tmpls: Templates) -> None:
+    def add_objtype(cls, objtype: str, typedef: ObjTypeDef) -> None:
+        schema = typedef.schema
+        tmpls = typedef.templates
+
         cls.schemas[objtype] = schema
         cls.templates[objtype] = tmpls
 
-        # Create a directive for defining object.
-        cls.directives[objtype] = ObjDefineDirective.derive(
-            objtype, schema, tmpls.content
-        )
+        # Create a directive for documenting object.
+        if typedef.auto:
+            cls.directives[objtype] = AutoObjDefineDirective.derive(
+                objtype,
+                schema,
+                tmpls.obj,
+            )
+        else:
+            cls.directives[objtype] = ObjDefineDirective.derive(
+                objtype,
+                schema,
+                tmpls.obj,
+            )
 
         def mkrole(reftype: RefType):
             """Create and register role for referencing object."""
@@ -265,73 +286,83 @@ def _get_index_anchor(self, reftype: str, refval: str) -> tuple[str, str]:
 
 
 class ObjDefineDirective(StrictDataDefineDirective):
+    """Methods that override from parent."""
+
     @override
     def process_pending_node(self, n: pending_node) -> bool:
         if n.template == self.template:
-            n.hook_rendered_node(self._setup_objdesc)
-
+            n.hook_rendered_nodes(self._build_objdesc)
         return super().process_pending_node(n)
 
-    def _setup_objdesc(self, pending: pending_node, rendered: rendered_node) -> None:
+    """Methods used internal."""
+
+    def _build_objdesc(self, pending: pending_node, rendered: list[nodes.Node]) -> None:
         """Wrap rendered.children into ObjectDescription.
 
         TODO: considier inherit from ObjectDescription directive?
 
         Before::
 
-            <rendered_node>
-                <...> # children
+            <nodes...> # the pass-in argument: ``ns``
 
         After::
 
-            <rendered_node>
-                <desc>
-                  <desc_signature>
-                      <desc_name>
-                          <pending_node> # header, wait for rendering
-                  <desc_content>
-                      <...> # the original children
+            <desc>
+              <desc_signature>
+                  <desc_name>
+                      <pending_node> # header, wait for rendering
+              <desc_content>
+                  <nodes...> # the original ``ns``
         """
-
-        domain, objtype = self._get_obj_domain_and_type()
-
-        def update_domaon_atts(node: nodes.Element):
-            """Attach domain related info to node."""
-            node['domain'] = domain.name
-            # 'desctype' is a backwards compatible attribute
-            node['objtype'] = node['desctype'] = objtype
-            node['classes'].extend([domain.name, objtype])
+        domain, objtype = self.get_obj_domain_and_type()
 
         if (hdrtmpl := domain.templates[objtype].header) is None:
             # No header template available, no need to generate objdesc.
-            update_domaon_atts(rendered)
             return
 
         # Queue a rendering for header, and setup anchor when rendering done.
         hdrnode = pending_node(pending.data, hdrtmpl, inline=True)
-        hdrnode.hook_rendered_node(self._setup_objdesc_anchor)
+        hdrnode.hook_rendered_nodes(self._setup_signode_anchor)
         self.queue_pending_node(hdrnode)
 
         # Construct ObjectDescription.
         signode = addnodes.desc_signature('', '', addnodes.desc_name('', '', hdrnode))
-        contnode = addnodes.desc_content('', *rendered.children)
+        contnode = addnodes.desc_content('', *rendered)
         descnode = addnodes.desc('', signode, contnode)
-        update_domaon_atts(descnode)
+        self.update_domain_atts(descnode)
 
-        # Add descnode as child of rendered.
+        # Replace the pass-in node list.
         rendered.clear()
-        rendered += descnode
+        rendered.append(descnode)
 
-    def _setup_objdesc_anchor(
-        self, pending: pending_node, rendered: rendered_node
+    def _setup_signode_anchor(
+        self, pending: pending_node, rendered: list[nodes.Node]
     ) -> None:
-        domain, objtype = self._get_obj_domain_and_type()
-
         ahrnode = find_parent(pending, addnodes.desc_signature)
         assert ahrnode
-        obj = rendered.data
+        obj = pending.data
         assert isinstance(obj, ParsedData)
 
+        self.setup_anchor(ahrnode, obj)
+
+    """Helpers methods for self and subclasses."""
+
+    def get_obj_domain_and_type(self) -> tuple[ObjDomain, str]:
+        domainname, _, objtype = self.name.partition(':')
+        _domain = self.env.get_domain(domainname)
+        return cast(ObjDomain, _domain), objtype
+
+    def update_domain_atts(self, node: nodes.Element):
+        """Attach domain related info to node."""
+        domain, objtype = self.get_obj_domain_and_type()
+        node['domain'] = domain.name
+        # 'desctype' is a backwards compatible attribute
+        node['objtype'] = node['desctype'] = objtype
+        node['classes'].extend([domain.name, objtype])
+
+    def setup_anchor(self, ahrnode: nodes.Element, obj: Object) -> None:
+        domain, objtype = self.get_obj_domain_and_type()
+
         objids = get_object_uniq_ids(self.schema, obj)
         ahrterm = ValueWrapper(objids[0]).as_str() if objids else None
         ahrid = make_id(self.env, self.state.document, prefix=objtype, term=ahrterm)
@@ -351,8 +382,8 @@ def _setup_objdesc_anchor(
             report = Report(
                 'Duplicate identifier',
                 'INFO',
-                source=pending.source,
-                line=pending.line,
+                source=ahrnode.source,
+                line=ahrnode.line,
             )
             report.text(
                 f'Duplicate object identifier at {self.env.docname}#{ahrid}, '
@@ -364,10 +395,82 @@ def _setup_objdesc_anchor(
             blkparent = find_nearest_block_element(ahrnode) or self.state.document
             blkparent += report
 
-    def _get_obj_domain_and_type(self) -> tuple[ObjDomain, str]:
-        domainname, objtype = self.name.split(':', 1)
-        _domain = self.env.get_domain(domainname)
-        return cast(ObjDomain, _domain), objtype
+
+class AutoObjDefineDirective(ObjDefineDirective):
+    """Methods that override from parent."""
+
+    @override
+    @classmethod
+    def derive(
+        cls, name: str, schema: Schema, tmpl: Template
+    ) -> type[StrictDataDefineDirective]:
+        subcls = super().derive(name, schema, tmpl)
+        if schema.name and schema.name.required:
+            # data.name is resolved from external.
+            subcls.required_arguments = 0
+            subcls.optional_arguments = 1
+        return subcls
+
+    @override
+    def process_pending_node(self, n: pending_node) -> bool:
+        if (
+            n.template == self.template
+            and isinstance(n.data, PendingData)
+            and self._require_external_header(n.data.schema, n.data.raw)
+        ):
+            n.hook_raw_data(self._resolve_external_header)
+            return super(StrictDataDefineDirective, self).process_pending_node(n)
+
+        return super().process_pending_node(n)
+
+    """Methods used internal."""
+
+    def _require_external_header(self, schema: Schema, data: RawData) -> bool:
+        # If the data.name is not given (None) or a underscore('_'), we think
+        # the object requires an external name.
+        #
+        # The special underscore is for compatible with sphinxnotes-any<3.
+        # See also https://sphinx.silverrainz.me/any/tips.html#documenting-section-and-documentation
+        if not schema.name:
+            return False
+        if schema.name.ctype is None:
+            return data.name in (None, '_')
+        # HACK: We have to parse the data.name here.
+        try:
+            val = schema.name.parse(data.name)
+        except ValueError:
+            return False
+        return ValueWrapper(val).as_str() == '_'
+
+    def _resolve_external_header(self, pending: pending_node, raw: RawData) -> None:
+        domain, objtype = self.get_obj_domain_and_type()
+
+        if (hdrtmpl := domain.templates[objtype].header) is None:
+            # No header template available, no need to generate objdesc.
+            return
+        if not (title := find_titular_node_upward(self.state.parent)):
+            return
+
+        if raw.name is None:
+            raw.name = title.astext()
+        else:
+            # HACK: See also _require_external_header.
+            # TODO: Introduce a new extra context?
+            raw.name = raw.name.replace('_', title.astext(), count=1)
+
+        pending_title = pending_node(pending.data, hdrtmpl, inline=True)
+        pending_title.hook_rendered_nodes(self._setup_external_anchor)
+        self.queue_pending_node(pending_title)
+
+        # Replace title's children with pending node.
+        title.clear()
+        title += pending_title
+
+    def _setup_external_anchor(
+        self, pending: pending_node, rendered: list[nodes.Node]
+    ) -> None:
+        assert isinstance(pending.data, ParsedData)
+        self.setup_anchor(pending.parent, pending.data)
 
 
 # =================

src/sphinxnotes/any/obj.py

@@ -91,7 +91,7 @@ class Templates:
     cross-references, and etc."""
 
     """Templates for rendering object"""
-    content: Template
+    obj: Template
     header: Template | None
 
     # embed: Templates
@@ -113,7 +113,7 @@ def __init__(
         ref_by: dict[str, str] = {},
         debug: bool = False,
     ):
-        self.content = Template(content, Phase.Parsing, debug)
+        self.obj = Template(content, Phase.Parsing, debug)
         self.header = Template(header, Phase.Parsing, debug) if header else None
         self.ref = Template(ref, Phase.PostTranform, debug)
         self.ref_by = {
@@ -127,6 +127,16 @@ def get_ref_by(self, reftype: RefType) -> Template:
         return self.ref
 
 
+@dataclass
+class ObjTypeDef:
+    schema: Schema
+    templates: Templates
+
+    #: When enabled, resolving external nodes for supplement the missing
+    # RawData.name and RawData.content.
+    auto: bool
+
+
 # ============================
 # Basic types for object index
 # ============================