Detailed API docs

docs/api.rst

@@ -1,27 +1,32 @@
-=============
-API Reference
-=============
+==============
+API References
+==============
 
-Data Types
-==========
+Value, Data, Field and Schema
+=============================
 
-.. autotype:: sphinxnotes.render.PlainValue
-.. autotype:: sphinxnotes.render.Value
+.. autoclass:: sphinxnotes.render.PlainValue
+.. autoclass:: sphinxnotes.render.Value
 
 .. autoclass:: sphinxnotes.render.RawData
+   :members: name, attrs, content
+   :undoc-members:
+
 .. autoclass:: sphinxnotes.render.ParsedData
+   :members: name, attrs, content
+   :undoc-members:
 
 .. autoclass:: sphinxnotes.render.Field
+   :members: parse
+
 .. autoclass:: sphinxnotes.render.Schema
+   :members: name, attrs, content
+   :undoc-members:
 
 .. autoclass:: sphinxnotes.render.data.Registry
+   :members:
 
-   .. automethod:: add_type
-   .. automethod:: add_form
-   .. automethod:: add_flag
-   .. automethod:: add_by_option
-
-      .. autotype:: sphinxnotes.render.data.ByOptionStore
+   .. autotype:: sphinxnotes.render.data.ByOptionStore
 
 The Render Pipeline
 ===================
@@ -38,14 +43,21 @@ Context
 Extra Context
 -------------
 
-.. autoclass:: sphinxnotes.render.ExtraContextGenerator
+.. autoclass:: sphinxnotes.render.GlobalExtraContxt
+.. autoclass:: sphinxnotes.render.ParsePhaseExtraContext
+.. autoclass:: sphinxnotes.render.TransformPhaseExtraContext
+
 .. autoclass:: sphinxnotes.render.ExtraContextRegistry
+   :members:
 
 Template
 --------
 
 .. autoclass:: sphinxnotes.render.Template
+   :members:
+
 .. autoclass:: sphinxnotes.render.Phase
+   :members:
 
 Pipeline
 --------

docs/conf.py

@@ -11,7 +11,7 @@
 
 project = 'sphinxnotes-render'
 author = 'Shengyu Zhang'
-copyright = "2025, " + author
+copyright = '2025, ' + author
 
 # The full version, including alpha/beta/rc tags
 version = release = '1.0a0'
@@ -57,9 +57,9 @@
 html_theme = 'furo'
 
 html_theme_options = {
-    "source_repository": "https://github.com/sphinx-notes/data/",
-    "source_branch": "master",
-    "source_directory": "docs/",
+    'source_repository': 'https://github.com/sphinx-notes/data/',
+    'source_branch': 'master',
+    'source_directory': 'docs/',
 }
 
 # The URL which points to the root of the HTML documentation.
@@ -88,15 +88,17 @@
 gtagjs_ids = ['G-E4SNX0WZYV']
 
 extensions.append('sphinx.ext.autodoc')
-autoclass_content = 'init'
-autodoc_typehints = 'description'
+# autoclass_content = 'init'
+autodoc_typehints = 'signature'
+autodoc_typehints_format = 'short'
+autodoc_inherit_docstrings = False
 
 extensions.append('sphinx.ext.intersphinx')
 intersphinx_mapping = {}
 
 extensions.append('sphinx_sitemap')
-sitemap_filename = "sitemap.xml"
-sitemap_url_scheme = "{link}"
+sitemap_filename = 'sitemap.xml'
+sitemap_url_scheme = '{link}'
 
 extensions.append('sphinxext.opengraph')
 ogp_site_url = html_baseurl
@@ -118,12 +120,29 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../src/sphinxnotes'))
-extensions.append('render')
+
+sys.path.insert(0, os.path.abspath('../src/'))
+extensions.append('sphinxnotes.render')
+
+# Override type aliases for autodoc (PEP 695 type statement not well supported)
+# import sphinxnotes.render
+# sphinxnotes.render.data.PlainValue = bool | int | float | str | object
+# sphinxnotes.render.PlainValue = bool | int | float | str | object
+# sphinxnotes.render.data.Value = None | sphinxnotes.render.PlainValue | list[sphinxnotes.render.PlainValue]
+# sphinxnotes.render.Value = None | sphinxnotes.render.PlainValue | list[sphinxnotes.render.PlainValue]
 
 # CUSTOM CONFIGURATION
 
-_ = extensions.pop() # no need to load extension
-primary_domain = 'py'
+autodoc_default_options = {
+    'member-order': 'bysource',
+}
+
+extensions.append('sphinxnotes.data')
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master', None),
+}
 
-extensions.append('sphinx.ext.doctest')
+def setup(app):
+    app.add_object_type('event', 'event')

docs/dsl.rst

@@ -1,27 +1,17 @@
-=====================
-Field Declaration DSL
-=====================
+==========================
+Field Description Language
+==========================
 
 .. default-domain:: py
 .. highlight:: python
 .. role:: py(code)
    :language: Python
 
 
-The Field Declaration DSL is a Domain Specific Language (DSL) that used to
-define the type and structure of field values. A DSL declaration consists of
+The Field Description Language is a Domain Specific Language (DSL) that used to
+define the type and structure of field values. An FDL declaration consists of
 one or more :term:`modifier`\ s separated by commas (``,``).
 
-Python API
-==========
-
-User can create a :class:`sphinxnotes.render.Field` from DSL and use it to parse
-string to :type:`sphinxnotes.render.Value`:
-
->>> from sphinxnotes.render import Field
->>> Field.from_dsl('list of int').parse('1,2,3')
-[1, 2, 3]
-
 Syntax
 ======
 
@@ -34,17 +24,28 @@ Syntax
    Modifier
       There are four categories of modifiers:
 
-      Type modifier
-         Specifies the element type (scalar value)
+   Type modifier
+      Specifies the element type (scalar value)
+
+   Form modifier
+      Specifies a container type with element type
 
-      Form modifier
-         Specifies a container type with element type
+   Flag
+      A boolean flag (either on or off)
 
-      Flag
-         A boolean flag (either on or off)
+   By-Option
+      A key-value option
+
+Python API
+==========
+
+User can create a :class:`sphinxnotes.render.Field` from FDL and use it to parse
+string to :type:`sphinxnotes.render.Value`:
+
+>>> from sphinxnotes.render import Field
+>>> Field.from_dsl('list of int').parse('1,2,3')
+[1, 2, 3]
 
-      By-Option
-         A key-value option
 
 Type
 ====
@@ -179,10 +180,10 @@ DSL                 Input     Result
 ``int, sep by ':'`` ``1:2:3`` :py:`[1, 2, 3]`
 =================== ========= ================
 
-Extending the DSL
+Extending the FDL
 =================
 
-You can extend the DSL by registering custom types, flags, and by-options
+You can extend the FDL by registering custom types, flags, and by-options
 through the :attr:`~sphinxnotes.render.Registry.data` attribute of
 :data:`sphinxnotes.render.REGISTRY`.
 

docs/index.rst

@@ -53,6 +53,7 @@ Contents
 .. toctree::
    :caption: Contents
 
+   tmpl
    dsl
    api
    changelog

docs/tmpl.rst

@@ -0,0 +1,100 @@
+==========
+Templating
+==========
+
+We use Jinja2_ to rendering templating to markup text (usually reStructuredText).
+User should be familiar with Jinja2 before reading this document.
+
+.. _Jinja2: https://jinja.palletsprojects.com/en/stable/templates/
+
+.. _context:
+
+Data Context
+============
+
+Context defined by directives and roles consist of following `template variables`_:
+
+.. glossary::
+
+   ``{{ name }}``
+      For directive, it refer to the only argument, such as ``bar`` of
+      ``.. foo:: bar``.
+
+      For role, it refer to the name, such as ``foo`` of ``:foo:`bar```.
+
+   ``{{ attrs.xxx }}``
+      For directive, they refer to directive options 
+
+      For role, it is usually empty.
+
+      .. note::
+
+         You can also refer them without the ``attr.`` prefix (just ``{{ xxx }}``)
+         when there is no ambiguity.
+
+   ``{{ content }}``
+      For directive, it refers to the directive content.
+
+      For role, it refer to the interpreted text, such as ``bar`` of ``:foo:`bar```.
+
+The type of variables are depended on the corrsponding :doc:`dsl`.
+
+.. hint:: For extension developers:
+
+   Directive and roles refer to classes derived from
+   :py:class:`~sphinxnotes.render.BaseDataDefineRole` and
+   :py:class:`~sphinxnotes.render.BaseDataDefineDirective`.
+
+   The aboved context is refer to :py:class:`~sphinxnotes.render.ParsedData`.
+
+.. _template variables: https://jinja.palletsprojects.com/en/stable/templates/#variables
+
+Extra Contexts
+==============
+
+Extra context can be extending by implmenting one of the following classs:
+
+:py:class:`~sphinxnotes.render.GlobalExtraContxt`
+:py:class:`~sphinxnotes.render.ParsePhaseExtraContext`
+:py:class:`~sphinxnotes.render.TransformPhaseExtraContext`
+
+Phases
+======
+
+:py:class:`sphinxnotes.render.Phase`.
+
+.. example::
+   :style: grid
+
+   .. data:render::
+      :on: parsing
+
+      - The current document has
+        {{ _doc.sections | length }} section(s).
+      - The current proejct has
+        {{ _sphinx.env.all_docs | length }} document(s).
+
+.. example::
+   :style: grid
+
+   .. data:render::
+      :on: parsed
+
+      - The current document has
+        {{ _doc.sections | length }} section(s).
+      - The current proejct has
+        {{ _sphinx.env.all_docs | length }} document(s).
+
+.. example::
+   :style: grid
+
+   .. data:render::
+      :on: resolving
+
+      - The current document has
+        {{ _doc.sections | length }} section(s).
+      - The current proejct has
+        {{ _sphinx.env.all_docs | length }} document(s).
+
+TODO
+====

src/sphinxnotes/render/__init__.py

@@ -6,7 +6,6 @@
 :license: BSD, see LICENSE for details.
 """
 
-from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from . import meta
@@ -29,7 +28,13 @@
 )
 from .ctx import PendingContext, ResolvedContext
 from .ctxnodes import pending_node
-from .extractx import ExtraContextRegistry, ExtraContextGenerator
+from .extractx import (
+    ExtraContextRegistry,
+    ExtraContextGenerator,
+    GlobalExtraContxt,
+    ParsePhaseExtraContext,
+    TransformPhaseExtraContext,
+)
 from .pipeline import BaseContextRole, BaseContextDirective
 from .sources import (
     UnparsedData,
@@ -57,6 +62,10 @@
     'Host',
     'PendingContext',
     'ResolvedContext',
+    'GlobalExtraContxt',
+    'ParsePhaseExtraContext',
+    'TransformPhaseExtraContext',
+    'TransformPhaseExtraContext',
     'pending_node',
     'BaseContextRole',
     'BaseContextDirective',
@@ -81,6 +90,7 @@ def extra_context(cls) -> ExtraContextRegistry:
 
 REGISTRY = Registry()
 
+
 def setup(app: Sphinx):
     meta.pre_setup(app)