Merge pull request #39 from sphinx-notes/v3

 Any domain 3.0

.github/workflows/test.yml

@@ -5,11 +5,14 @@ on:
   schedule:
     - cron: '0 7 * * 6'
 jobs:
-  test-ubuntu:
+  test:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
+    - uses: actions/setup-python@v5
+      with:
+        python-version-file: 'pyproject.toml'
     - name: Install the dependencies
-      run: python3 -m pip install sphinx -r ./requirements.txt
+      run: python3 -m pip install .[dev]
     - name: Build
       run: make test

docs/_schemas/cat.py

@@ -1,12 +1,12 @@
 from textwrap import dedent
-from any import Schema, Field
+from any.api import Schema, Field
 
 cat = Schema(
     'cat',
-    name=Field(referenceable=True, form=Field.Form.LINES),
+    name=Field(ref=True, form=Field.Forms.LINES),
     attrs={
-        'id': Field(unique=True, referenceable=True, required=True),
-        'color': Field(referenceable=True),
+        'id': Field(uniq=True, ref=True, required=True),
+        'color': Field(ref=True),
         'picture': Field(),
     },
     description_template=dedent("""

docs/_schemas/dog1.py

@@ -4,8 +4,8 @@
 dog = Schema(
     'dog',
     attrs={
-        'breed': Field(referenceable=True),
-        'color': Field(referenceable=True, form=Field.Form.WORDS),
+        'breed': Field(ref=True),
+        'color': Field(ref=True, form=Field.Forms.WORDS),
     },
     description_template=dedent("""
         :Breed: {{ breed }}

docs/_schemas/dog2.py

@@ -1,11 +1,11 @@
 from textwrap import dedent
-from any import Schema, Field
+from any.api import Schema, Field
 
 dog = Schema(
     'dog',
     attrs={
-        'breed': Field(referenceable=True),
-        'color': Field(referenceable=True, form=Field.Form.WORDS),
+        'breed': Field(ref=True),
+        'color': Field(ref=True, form=Field.Forms.WORDS),
     },
     description_template=dedent("""
         :Breed: :any:dog.breed:`{{ breed }}`

docs/_schemas/tmplvar.py

@@ -1,9 +1,9 @@
 from textwrap import dedent
-from any import Schema, Field
+from any.api import Schema, Field
 
 tmplvar = Schema(
     'tmplvar',
-    name=Field(unique=True, referenceable=True),
+    name=Field(uniq=True, ref=True),
     attrs={
         'type': Field(),
         'conf': Field(),

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,35 +114,36 @@
 
 # 
 # DOG FOOD CONFIGURATION START
-from any import Schema, Field as F
-sys.path.insert(0, os.path.abspath('.'))
+from any.api import Schema, Field as F, by_year, by_month
 
 version_schema = Schema('version',
-                        name=F(unique=True, referenceable=True, required=True, form=F.Form.LINES),
-                        attrs={'date': F(referenceable=True)},
-                        content=F(form=F.Form.LINES),
+                        name=F(uniq=True, ref=True, required=True, form=F.Forms.LINES),
+                        attrs={
+                            'date': F(ref=True, indexers=[by_year, by_month]),
+                        },
+                        content=F(form=F.Forms.LINES),
                         description_template=open('_templates/version.rst', 'r').read(),
                         reference_template='🏷️{{ title }}',
                         missing_reference_template='🏷️{{ title }}',
                         ambiguous_reference_template='🏷️{{ title }}')
 confval_schema = Schema('confval',
-                        name=F(unique=True, referenceable=True, required=True, form=F.Form.LINES),
+                        name=F(uniq=True, ref=True, required=True, form=F.Forms.LINES),
                         attrs={
                             'type': F(),
                             'default': F(),
-                            'choice': F(form=F.Form.WORDS),
+                            'choice': F(form=F.Forms.WORDS),
                             'versionadded': F(),
-                            'versionchanged': F(form=F.Form.LINES),
+                            'versionchanged': F(form=F.Forms.LINES),
                         },
                         content=F(),
                         description_template=open('_templates/confval.rst', 'r').read(),
                         reference_template='⚙️{{ title }}',
                         missing_reference_template='⚙️{{ title }}',
                         ambiguous_reference_template='⚙️{{ title }}')
 example_schema = Schema('example',
-                        name=F(referenceable=True),
+                        name=F(ref=True),
                         attrs={'style': F()},
-                        content=F(form=F.Form.LINES),
+                        content=F(form=F.Forms.LINES),
                         description_template=open('_templates/example.rst', 'r').read(),
                         reference_template='📝{{ title }}',
                         missing_reference_template='📝{{ title }}',

docs/usage.rst

@@ -15,7 +15,7 @@ Defining Schema
 
 The necessary python classes for writing schema are listed here:
 
-.. autoclass:: any.Schema
+.. autoclass:: any.api.Schema
 
    Class-wide shared special keys used in template rendering context:
 
@@ -26,15 +26,15 @@ The necessary python classes for writing schema are listed here:
 
    |
 
-.. autoclass:: any.Field
+.. autoclass:: any.api.Field
 
    |
 
-.. autoclass:: any.Field.Form
+.. autoclass:: any.api.Field.Forms
 
-   .. autoattribute:: any.Field.Form.PLAIN
-   .. autoattribute:: any.Field.Form.WORDS
-   .. autoattribute:: any.Field.Form.LINES
+   .. autoattribute:: any.api.Field.Forms.PLAIN
+   .. autoattribute:: any.api.Field.Forms.WORDS
+   .. autoattribute:: any.api.Field.Forms.LINES
 
 Documenting Object
 ==================

pyproject.toml

@@ -27,7 +27,7 @@ classifiers = [
     "Topic :: Documentation :: Sphinx",
 ]
 
-requires-python = ">=3.8"
+requires-python = ">=3.12"
 dependencies = [
     "Sphinx >= 4",
     "Jinja2",

src/sphinxnotes/any/__init__.py

@@ -10,24 +10,21 @@
 
 from __future__ import annotations
 from typing import TYPE_CHECKING
+from importlib.metadata import version
+
 from sphinx.util import logging
 
 from .template import Environment as TemplateEnvironment
 from .domain import AnyDomain, warn_missing_reference
-from .schema import Schema, Field
+from .objects import Schema
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
     from sphinx.config import Config
 
-__version__ = '2.3.1'
 
 logger = logging.getLogger(__name__)
 
-# Export
-Field = Field
-Schema = Schema
-
 
 def _config_inited(app: Sphinx, config: Config) -> None:
     AnyDomain.name = config.any_domain_name
@@ -51,4 +48,4 @@ def setup(app: Sphinx):
     app.connect('config-inited', _config_inited)
     app.connect('warn-missing-reference', warn_missing_reference)
 
-    return {'version': __version__}
+    return {'version': version('sphinxnotes.any')}

src/sphinxnotes/any/api.py

@@ -0,0 +1,27 @@
+"""
+sphinxnotes.any.api
+~~~~~~~~~~~~~~~~~~~
+
+Public API for building configuration of extension.
+(such as object schema, and so on).
+
+:copyright: Copyright 2024 Shengyu Zhang
+:license: BSD, see LICENSE for details.
+"""
+
+from .objects import Schema, Field
+from .indexers import LiteralIndexer, PathIndexer, YearIndexer, MonthIndexer
+
+# Object schema.
+Schema = Schema
+Field = Field
+
+# Indexers.
+LiteralIndexer = LiteralIndexer
+PathIndexer = PathIndexer
+YearIndexer = YearIndexer
+MonthIndexer = MonthIndexer
+
+# Indexer wrappers.
+by_year = YearIndexer()
+by_month = MonthIndexer()

src/sphinxnotes/any/directives.py

@@ -15,13 +15,12 @@
 from docutils.nodes import Node, Element, fully_normalize_name
 from docutils.statemachine import StringList
 from docutils.parsers.rst import directives
-
 from sphinx import addnodes
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import make_id, nested_parse_with_titles
 from sphinx.util import logging
 
-from .schema import Schema, Object
+from .objects import Schema, Object
 
 logger = logging.getLogger(__name__)