refactor: Rework role and index constructing (#41)

Completed all the functions lost compared to v2.

Author: SilverRainZ

docs/_templates/version.rst

@@ -1,5 +1,5 @@
 
-:Date: :version.date.by-year:`📅{{ date }} <{{ date }}>`
+:Date: :version.date+by-year:`📅{{ date }} <{{ date }}>`
 :Download: :tag:`{{ title }}`
 
 {% for line in content %}

src/sphinxnotes/any/domain.py

@@ -18,7 +18,7 @@
 from sphinx.util import logging
 from sphinx.util.nodes import make_refnode
 
-from .schema import Schema, Object
+from .schema import Schema, Object, RefType, Indexer, LiteralIndexer
 from .directives import AnyDirective
 from .roles import AnyRole
 from .indices import AnyIndex
@@ -49,9 +49,9 @@ class AnyDomain(Domain):
     roles: dict[str, RoleFunction] = {}
     #: A list of Index subclasses
     indices: list[type[AnyIndex]] = []
-    #: AnyDomain specific: type -> index class
+    #: AnyDomain specific: reftype -> index class
     _indices_for_reftype: dict[str, type[AnyIndex]] = {}
-    #: AnyDomain specific: type -> Schema instance
+    #: AnyDomain specific: objtype -> Schema instance
     _schemas: dict[str, Schema] = {}
 
     initial_data: dict[str, Any] = {
@@ -120,7 +120,7 @@ def resolve_xref(
         logger.debug('[any] resolveing xref of %s', (typ, target))
 
         reftype = RefType.parse(typ)
-        objtype, objfield, objidx = reftype.objtype, reftype.field, reftype.index
+        objtype, objfield, objidx = reftype.objtype, reftype.field, reftype.indexer
         objids = set()
         if objidx:
             pass  # no need to lookup objds
@@ -142,10 +142,7 @@ def resolve_xref(
         if len(objids) > 1 or objidx is not None:
             # Mulitple objects found or reference index explicitly,
             # create link to indices page.
-            (
-                todocname,
-                anchor,
-            ) = self._get_index_anchor(typ, target)
+            (todocname, anchor) = self._get_index_anchor(typ, target)
             if not has_explicit_title:
                 newtitle = schema.render_ambiguous_reference(title)
             logger.debug(
@@ -181,43 +178,51 @@ def add_schema(cls, schema: Schema) -> None:
         # Add to schemas dict
         cls._schemas[schema.objtype] = schema
 
-        # Generates reftypes for all referenceable fields
-        # For later use when generating roles and indices.
-        reftypes = [str(RefType(schema.objtype, None, None))]
-        for name, field in schema.fields(all=False):
-            if not field.ref:
-                continue
-
-            # Field is unique , use ``:objtype.field:`` to reference.
-            if field.uniq:
-                reftype = str(RefType(schema.objtype, name, None))
-                reftypes.append(reftype)
-                continue
-
-        for name, field in schema.fields(all=False):
-            # Field is not unique, link to index page.
-            for indexer in field.indexers:
-                reftype = str(RefType(schema.objtype, name, indexer.name))
-                reftypes.append(reftype)
-
-                # FIXME: name and content can not be index now
-                index = AnyIndex.derive(schema, name, indexer)
-                cls.indices.append(index)
-                cls._indices_for_reftype[reftype] = index
-
-        for reftype in reftypes:
-            field = RefType.parse(reftype).field
-            # Create role for referencing object by field
-            cls.roles[reftype] = AnyRole.derive(schema, field)(
+        def mkrole(reftype: RefType):
+            """Create and register role for referencing object."""
+            role = AnyRole(
                 # Emit warning when missing reference (node['refwarn'] = True)
                 warn_dangling=True,
                 # Inner node (contnode) would be replaced in resolve_xref method,
                 # so fix its class.
                 innernodeclass=literal,
             )
+            cls.roles[str(reftype)] = role
+            logger.debug(f'[any] make role {reftype} →  {type(role)}')
+
+        def mkindex(reftype: RefType, indexer: Indexer):
+            """Create and register object index."""
+            index = AnyIndex.derive(schema, reftype, indexer)
+            cls.indices.append(index)
+            cls._indices_for_reftype[str(reftype)] = index
+            logger.debug(f'[any] make index {reftype} →  {type(index)}')
+
+        # Create all-in-one role and index (do not distinguish reference fields).
+        reftypes = [RefType(schema.objtype)]
+        mkrole(reftypes[0])
+        mkindex(reftypes[0], LiteralIndexer())
+
+        # Create {field,indexer}-specificed role and index.
+        for name, field in schema.fields():
+            if field.ref:
+                reftype = RefType(schema.objtype, field=name)
+                reftypes.append(reftype)
+                mkrole(reftype)  # create a role to reference object(s)
+                # Create a fallback indexer, for possible ambiguous reference
+                # (if field is not unique).
+                mkindex(reftype, LiteralIndexer())
+
+            for indexer in field.indexers:
+                reftype = RefType(schema.objtype, field=name, indexer=indexer.name)
+                reftypes.append(reftype)
+                # Create role and index for reference objects by index.
+                mkrole(reftype)
+                mkindex(reftype, indexer)
 
         # TODO: document
-        cls.object_types[schema.objtype] = ObjType(schema.objtype, *reftypes)
+        cls.object_types[schema.objtype] = ObjType(
+            schema.objtype, *[str(x) for x in reftypes]
+        )
         # Generates directive for creating object.
         cls.directives[schema.objtype] = AnyDirective.derive(schema)
 
@@ -238,42 +243,9 @@ def warn_missing_reference(
     if domain and domain.name != AnyDomain.name:
         return None
 
-    objtype = RefType.parse(node['reftype']).objtype
+    reftype = RefType.parse(node['reftype'])
     target = node['reftarget']
 
-    msg = f'undefined {objtype}: {target}'
-    logger.warning(msg, location=node, type='ref', subtype=objtype)
+    msg = f'undefined reftype {reftype}: {target}'
+    logger.warning(msg, location=node, type='ref', subtype=reftype.objtype)
     return True
-
-
-class RefType(object):
-    """Reference type, used as role name and node['reftype'] and
-    and *typ* argument of :meth:`AnyDomain.resolve_xref` method."""
-
-    #: :attr:`ObjType.lname`
-    objtype: str
-    #: :attr:`.schema.Field.name`
-    field: str | None
-    #: :attr:`.schema.Indexer.name`
-    index: str | None
-
-    def __init__(self, objtype: str, field: str | None, index: str | None):
-        self.objtype = objtype
-        self.field = field
-        self.index = index
-
-    @classmethod
-    def parse(cls, reftype: str):
-        v = reftype.split('.', maxsplit=2)
-        objtype = v[0]
-        field = v[1] if len(v) > 1 else None
-        index = v[2][3:] if len(v) > 2 else None  # skip "by-"
-        return cls(objtype, field, index)
-
-    def __str__(self):
-        s = self.objtype
-        if self.field is not None:
-            s += '.' + self.field
-        if self.index is not None:
-            s += '.' + 'by-' + self.index
-        return s

src/sphinxnotes/any/indices.py

@@ -16,7 +16,7 @@
 from docutils import core, nodes
 from docutils.parsers.rst import roles
 
-from .schema import Schema, Value, Indexer, Category
+from .schema import Schema, Value, Indexer, Category, RefType
 
 logger = logging.getLogger(__name__)
 
@@ -28,34 +28,35 @@ class AnyIndex(Index):
 
     domain: Domain  # for type hint
     schema: Schema
-    field: str | None = None
+    reftype: RefType
     indexer: Indexer
 
     @classmethod
     def derive(
-        cls, schema: Schema, field: str | None, indexer: Indexer
+        cls, schema: Schema, reftype: RefType, indexer: Indexer
     ) -> type['AnyIndex']:
         """Generate an AnyIndex child class for indexing object."""
-        # TODO: add Indexer.name
-        if field:
-            typ = f'Any{schema.objtype.title()}{field.title()}IndexBy{indexer.name.title()}'
-            name = schema.objtype + '.' + field + '.by-' + indexer.name  # TODO: RefType
-            localname = f'{schema.objtype.title()} {field.title()} Reference Index by {indexer.name.title()}'
-        else:
-            typ = f'Any{schema.objtype.title()}IndexBy{indexer.name.title()}'
-            name = schema.objtype + '.by-' + indexer.name  # TODO: RefType
+        if reftype.field:
+            clsname = f'Any{reftype.objtype.title()}{reftype.field.title()}Index'
             localname = (
-                f'{schema.objtype.title()} Reference Index by {indexer.name.title()}'
+                f'{reftype.objtype.title()} {reftype.field.title()} Reference Index'
             )
+        else:
+            clsname = f'Any{reftype.objtype.title()}Index'
+            localname = f'{reftype.objtype.title()} Reference Index'
+        if reftype.indexer:
+            clsname += 'By' + reftype.indexer.title()
+            localname += ' by ' + reftype.indexer.title()
         return type(
-            typ,
+            clsname,
             (cls,),
             {
-                'name': name,
+                # HTML builder will generate /<domain>-<name>.html index page.
+                'name': str(reftype),
                 'localname': localname,
                 'shortname': 'references',
                 'schema': schema,
-                'field': field,
+                'reftype': reftype,
                 'indexer': indexer,
             },
         )
@@ -74,9 +75,9 @@ def generate(
 
         objrefs = sorted(self.domain.data['references'].items())
         for (objtype, objfield, objref), objids in objrefs:
-            if objtype != self.schema.objtype:
+            if objtype != self.reftype.objtype:
                 continue
-            if self.field and objfield != self.field:
+            if self.reftype.field and objfield != self.reftype.field:
                 continue
 
             # TODO: pass a real Value
@@ -124,7 +125,7 @@ def generate(
     def _generate_index_entry(
         self, objid: str, ignore_docnames: Iterable[str] | None, category: Category
     ) -> IndexEntry | None:
-        docname, anchor, obj = self.domain.data['objects'][self.schema.objtype, objid]
+        docname, anchor, obj = self.domain.data['objects'][self.reftype.objtype, objid]
         if ignore_docnames and docname not in ignore_docnames:
             return None
         name = self.schema.title_of(obj) or objid

src/sphinxnotes/any/roles.py

@@ -13,8 +13,6 @@
 from sphinx.util import logging
 from sphinx.roles import XRefRole
 
-from .schema import Schema
-
 logger = logging.getLogger(__name__)
 
 
@@ -25,11 +23,7 @@ class AnyRole(XRefRole):
     objtype.
     """
 
-    @classmethod
-    def derive(cls, schema: Schema, field: str | None = None) -> type['AnyRole']:
-        """Generate an AnyRole child class for referencing object."""
-        return type(
-            'Any%s%sRole' % (schema.objtype.title(), field.title() if field else ''),
-            (cls,),
-            {},
-        )
+    # NOTE: derive is not necessary for now.
+    # @classmethod
+    # def derive(cls) -> type['AnyRole']:
+    #     pass

src/sphinxnotes/any/schema.py

@@ -353,9 +353,7 @@ class Forms:
     ref: bool = False
     required: bool = False
     form: Form = Forms.PLAIN
-    indexers: list[Indexer] = dataclasses.field(
-        default_factory=lambda: [LiteralIndexer()]
-    )
+    indexers: list[Indexer] = dataclasses.field(default_factory=lambda: [])
 
     def value_of(self, rawval: str | None) -> Value:
         if rawval is None:
@@ -438,7 +436,9 @@ def __init__(
             else:
                 has_unique = field.uniq
 
-    def fields(self, all=True) -> list[tuple[str, Field]]:
+    def fields(
+        self, exclude_name: bool = False, exclude_content: bool = False
+    ) -> list[tuple[str, Field]]:
         """Return all fields of schema, including name and content.
 
         .. note::
@@ -448,9 +448,9 @@ def fields(self, all=True) -> list[tuple[str, Field]]:
         """
 
         fields = list(self.attrs.items())
-        if all and self.content is not None:
+        if not exclude_content and self.content is not None:
             fields.insert(0, (self.CONTENT_KEY, self.content))
-        if all and self.name is not None:
+        if not exclude_name and self.name is not None:
             fields.insert(0, (self.NAME_KEY, self.name))
         return fields
 
@@ -631,3 +631,58 @@ def __eq__(self, other: Any) -> bool:
         if not isinstance(other, Schema):
             return False
         return pickle.dumps(self) == pickle.dumps(other)
+
+
+class RefType(object):
+    """Reference type, object can be referenced:
+
+    - by type *objtype*
+    - by field *objtype*.*field*
+    - by field index *objtype*.*field*+by-*index*
+    """
+
+    #: Object type, same to :attr:`Schema.objtype`.
+    objtype: str
+    #: Name of field, see :attr:`.schema.Field.name`.
+    field: str | None
+    #: Name of indexer, see :attr:`.schema.Indexer.name`.
+    indexer: str | None
+
+    def __init__(
+        self, objtype: str, field: str | None = None, indexer: str | None = None
+    ):
+        self.objtype = objtype
+        self.field = field
+        self.indexer = indexer
+
+    @classmethod
+    def parse(cls, reftype: str):
+        """Format: <objtype>[.<field>[+<action>]]. Possible action:
+
+        - by-<indexer>
+        """
+
+        if '+' in reftype:
+            reftype, action = reftype.split('+', 1)
+            if action.startswith('by-'):
+                index = action[3:]
+            else:
+                raise ValueError(f'unknown action {action} in RefType {reftype}')
+        else:
+            index = None
+
+        if '.' in reftype:
+            objtype, field = reftype.split('.', 1)
+        else:
+            objtype, field = reftype, None
+
+        return cls(objtype, field, index)
+
+    def __str__(self):
+        """Used as role name and index name."""
+        s = self.objtype
+        if self.field:
+            s += '.' + self.field
+        if self.indexer:
+            s += '+' + 'by-' + self.indexer
+        return s