Multiple indices support (#40)

- Refactor, better naming
- Add MonthIndexer
- Support multiple indexers
- Fix anchor support of index page

Author: SilverRainZ

docs/_templates/version.rst

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

docs/conf.py

@@ -114,13 +114,17 @@
 
 # 
 # DOG FOOD CONFIGURATION START
-from any import Schema, Field as F, DateClassifier
+from any import Schema, Field as F
+from any.schema import YearIndexer, MonthIndexer
 sys.path.insert(0, os.path.abspath('.'))
 
+by_year = YearIndexer()
+by_month = MonthIndexer()
+
 version_schema = Schema('version',
                         name=F(uniq=True, ref=True, required=True, form=F.Forms.LINES),
                         attrs={
-                            'date': F(ref=True, classifiers=[DateClassifier(['%Y-%m-%d'])]),
+                            'date': F(ref=True, indexers=[by_year, by_month]),
                         },
                         content=F(form=F.Forms.LINES),
                         description_template=open('_templates/version.rst', 'r').read(),

src/sphinxnotes/any/__init__.py

@@ -14,7 +14,7 @@
 
 from .template import Environment as TemplateEnvironment
 from .domain import AnyDomain, warn_missing_reference
-from .schema import Schema, Field, DateClassifier
+from .schema import Schema, Field
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -27,7 +27,6 @@
 # Re-Export
 Field = Field
 Schema = Schema
-DateClassifier = DateClassifier
 
 
 def _config_inited(app: Sphinx, config: Config) -> None:

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, PlainClassifier
+from .schema import Schema, Object
 from .directives import AnyDirective
 from .roles import AnyRole
 from .indices import AnyIndex
@@ -118,8 +118,12 @@ def resolve_xref(
         assert isinstance(contnode, literal)
 
         logger.debug('[any] resolveing xref of %s', (typ, target))
-        objtype, objfield = reftype_to_objtype_and_objfield(typ)
+
+        reftype = RefType.parse(typ)
+        objtype, objfield, objidx = reftype.objtype, reftype.field, reftype.index
         objids = set()
+        if objidx:
+            pass  # no need to lookup objds
         if objfield:
             # NOTE: To prevent change domain data, dont use ``objids = xxx``
             ids = self.references.get((objtype, objfield, target))
@@ -135,16 +139,9 @@ def resolve_xref(
         has_explicit_title = node['refexplicit']
         newtitle = None
 
-        if not objids:
-            # The pending_xref node may be resolved by intersphinx,
-            # so not emit warning here, see also warn_missing_reference.
-            return None
-        elif len(objids) == 1:
-            todocname, anchor, obj = self.objects[objtype, objids.pop()]
-            if not has_explicit_title:
-                newtitle = schema.render_reference(obj)
-        else:
-            # Mulitple objects found, we should create link to indices page.
+        if len(objids) > 1 or objidx is not None:
+            # Mulitple objects found or reference index explicitly,
+            # create link to indices page.
             (
                 todocname,
                 anchor,
@@ -155,6 +152,14 @@ def resolve_xref(
                 f'ambiguous {objtype} {target} in {self}, '
                 + f'ids: {objids} index: {todocname}#{anchor}'
             )
+        elif len(objids) == 1:
+            todocname, anchor, obj = self.objects[objtype, objids.pop()]
+            if not has_explicit_title:
+                newtitle = schema.render_reference(obj)
+        else:
+            # The pending_xref node may be resolved by intersphinx,
+            # so do not emit warning here, see also warn_missing_reference.
+            return None
 
         if newtitle:
             logger.debug(f'[any] rewrite title from {title} to {newtitle}')
@@ -176,18 +181,32 @@ def add_schema(cls, schema: Schema) -> None:
         # Add to schemas dict
         cls._schemas[schema.objtype] = schema
 
-        reftypes = [schema.objtype]
+        # 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
 
-            # Generates reftypes for all referenceable fields
-            # For later use when generating roles and indices.
-            reftype = objtype_and_objfield_to_reftype(schema.objtype, name)
-            reftypes.append(reftype)
+            # 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_to_objtype_and_objfield(reftype)
+            field = RefType.parse(reftype).field
             # Create role for referencing object by field
             cls.roles[reftype] = AnyRole.derive(schema, field)(
                 # Emit warning when missing reference (node['refwarn'] = True)
@@ -197,19 +216,6 @@ def add_schema(cls, schema: Schema) -> None:
                 innernodeclass=literal,
             )
 
-            # FIXME: name and content can not be index now
-            if field is not None:
-                classifiers = schema.attrs[field].classifiers
-            elif schema.name is not None:
-                classifiers = schema.name.classifiers
-            else:
-                classifiers = [PlainClassifier()]
-            # Generates index for indexing object by fields
-            for indexer in classifiers:
-                index = AnyIndex.derive(schema, field, indexer)
-                cls.indices.append(index)
-                cls._indices_for_reftype[reftype] = index  # TODO: mulitple catelogers.
-
         # TODO: document
         cls.object_types[schema.objtype] = ObjType(schema.objtype, *reftypes)
         # Generates directive for creating object.
@@ -222,8 +228,8 @@ def _get_index_anchor(self, reftype: str, refval: str) -> tuple[str, str]:
         .. warning:: This is no public API of sphinx and may broken in future version.
         """
         domain = self.name
-        index = self._indices_for_reftype[reftype].name
-        return f'{domain}-{index}', f'cap-{refval}'
+        index = self._indices_for_reftype[reftype]
+        return f'{domain}-{index.name}', index.indexer.anchor(refval)
 
 
 def warn_missing_reference(
@@ -232,20 +238,42 @@ def warn_missing_reference(
     if domain and domain.name != AnyDomain.name:
         return None
 
-    objtype, _ = reftype_to_objtype_and_objfield(node['reftype'])
+    objtype = RefType.parse(node['reftype']).objtype
     target = node['reftarget']
 
     msg = f'undefined {objtype}: {target}'
     logger.warning(msg, location=node, type='ref', subtype=objtype)
     return True
 
 
-def reftype_to_objtype_and_objfield(reftype: str) -> tuple[str, str | None]:
-    """Helper function for converting reftype(role name) to object infos."""
-    v = reftype.split('.', maxsplit=1)
-    return v[0], v[1] if len(v) == 2 else None
+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
 
-def objtype_and_objfield_to_reftype(objtype: str, objfield: str) -> str:
-    """Helper function for converting object infos to reftype(role name)."""
-    return objtype + '.' + objfield
+    @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, Classifier, Classif
+from .schema import Schema, Value, Indexer, Category
 
 logger = logging.getLogger(__name__)
 
@@ -29,22 +29,24 @@ class AnyIndex(Index):
     domain: Domain  # for type hint
     schema: Schema
     field: str | None = None
-    classifier: Classifier
+    indexer: Indexer
 
     @classmethod
     def derive(
-        cls, schema: Schema, field: str | None, classifier: Classifier
+        cls, schema: Schema, field: str | None, 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()}Index'
-            name = schema.objtype + '.' + field  # TOOD: objtype_and_objfield_to_reftype
-            localname = f'{schema.objtype.title()} {field.title()} Reference Index'
+            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()}Index'
-            name = schema.objtype
-            localname = f'{schema.objtype.title()} Reference Index'
+            typ = f'Any{schema.objtype.title()}IndexBy{indexer.name.title()}'
+            name = schema.objtype + '.by-' + indexer.name  # TODO: RefType
+            localname = (
+                f'{schema.objtype.title()} Reference Index by {indexer.name.title()}'
+            )
         return type(
             typ,
             (cls,),
@@ -54,7 +56,7 @@ def derive(
                 'shortname': 'references',
                 'schema': schema,
                 'field': field,
-                'classifier': classifier,
+                'indexer': indexer,
             },
         )
 
@@ -64,11 +66,11 @@ def generate(
         """Override parent method."""
 
         # Single index for generating normal entries (subtype=0).
-        # Category (lv1) →  Category (for ordering objids) →  objids
-        singleidx: dict[Classif, dict[Classif, set[str]]] = {}
+        # Main Category →  Extra (for ordering objids) →  objids
+        singleidx: dict[Category, dict[Category, set[str]]] = {}
         # Dual index for generating entrie (subtype=1) and its sub-entries (subtype=2).
-        # Category (lv1) →  Category (lv2) →  Category (for ordering objids) →  objids
-        dualidx: dict[Classif, dict[Classif, dict[Classif, set[str]]]] = {}
+        # Main category  →  Sub-Category →  Extra (for ordering objids) →  objids
+        dualidx: dict[Category, dict[Category, dict[Category, set[str]]]] = {}
 
         objrefs = sorted(self.domain.data['references'].items())
         for (objtype, objfield, objref), objids in objrefs:
@@ -77,57 +79,57 @@ def generate(
             if self.field and objfield != self.field:
                 continue
 
-            # TODO: pass a real value
-            for catelog in self.classifier.classify(Value(objref)):
-                category = catelog.as_category()
-                entry = catelog.as_entry()
-                if entry is None:
-                    singleidx.setdefault(category, {}).setdefault(
-                        catelog, set()
-                    ).update(objids)
+            # TODO: pass a real Value
+            for category in self.indexer.classify(Value(objref)):
+                main = category.as_main()
+                sub = category.as_sub()
+                if sub is None:
+                    singleidx.setdefault(main, {}).setdefault(category, set()).update(
+                        objids
+                    )
                 else:
-                    dualidx.setdefault(category, {}).setdefault(entry, {}).setdefault(
-                        catelog, set()
+                    dualidx.setdefault(main, {}).setdefault(sub, {}).setdefault(
+                        category, set()
                     ).update(objids)
 
-        content: dict[Classif, list[IndexEntry]] = {}  # category →  entries
-        for category, entries in self._sort_by_catelog(singleidx):
-            index_entries = content.setdefault(category, [])
-            for category, objids in self._sort_by_catelog(entries):
+        content: dict[Category, list[IndexEntry]] = {}  # category →  entries
+        for main, entries in self._sort_by_category(singleidx):
+            index_entries = content.setdefault(main, [])
+            for main, objids in self._sort_by_category(entries):
                 for objid in objids:
-                    entry = self._generate_index_entry(objid, docnames, category)
+                    entry = self._generate_index_entry(objid, docnames, main)
                     if entry is None:
                         continue
                     index_entries.append(entry)
 
-        for category, entries in self._sort_by_catelog(dualidx):
-            index_entries = content.setdefault(category, [])
-            for entry, subentries in self._sort_by_catelog(entries):
-                index_entries.append(self._generate_empty_index_entry(entry))
-                for subentry, objids in self._sort_by_catelog(subentries):
+        for main, entries in self._sort_by_category(dualidx):
+            index_entries = content.setdefault(main, [])
+            for sub, subentries in self._sort_by_category(entries):
+                index_entries.append(self._generate_subcategory_index_entry(sub))
+                for subentry, objids in self._sort_by_category(subentries):
                     for objid in objids:
                         entry = self._generate_index_entry(objid, docnames, subentry)
                         if entry is None:
                             continue
                         index_entries.append(entry)
 
-        # sort by category, and map classif -> str
+        # sort by category, and map category -> str
         sorted_content = [
-            (classif.leaf, entries)
-            for classif, entries in self._sort_by_catelog(content)
+            (category.main, entries)
+            for category, entries in self._sort_by_category(content)
         ]
 
         return sorted_content, False
 
     def _generate_index_entry(
-        self, objid: str, ignore_docnames: Iterable[str] | None, category: Classif
+        self, objid: str, ignore_docnames: Iterable[str] | None, category: Category
     ) -> IndexEntry | None:
         docname, anchor, obj = self.domain.data['objects'][self.schema.objtype, objid]
         if ignore_docnames and docname not in ignore_docnames:
             return None
         name = self.schema.title_of(obj) or objid
-        subtype = category.index_entry_subtype
-        extra = category.leaf
+        subtype = category.index_entry_subtype()
+        extra = category.extra or ''
         objcont = self.schema.content_of(obj)
         if isinstance(objcont, str):
             desc = objcont
@@ -148,16 +150,17 @@ def _generate_index_entry(
             desc,  # description for the entry
         )
 
-    def _generate_empty_index_entry(self, category: Classif) -> IndexEntry:
+    def _generate_subcategory_index_entry(self, category: Category) -> IndexEntry:
+        assert category.sub is not None
         return IndexEntry(
-            category.leaf, category.index_entry_subtype, '', '', '', '', ''
+            category.sub, category.index_entry_subtype(), '', '', '', '', ''
         )
 
     _T = TypeVar('_T')
 
-    def _sort_by_catelog(self, d: dict[Classif, _T]) -> list[tuple[Classif, _T]]:
-        """Helper for sorting dict items by Category."""
-        return self.classifier.sort(d.items(), lambda x: x[0])
+    def _sort_by_category(self, d: dict[Category, _T]) -> list[tuple[Category, _T]]:
+        """Helper for sorting dict items by classif."""
+        return self.indexer.sort(d.items(), lambda x: x[0])
 
 
 def strip_rst_markups(rst: str) -> str: