update

Author: SilverRainZ

docs/api.rst

@@ -6,6 +6,7 @@ Value, Data, Field and Schema
 =============================
 
 .. autotype:: sphinxnotes.render.PlainValue
+
 .. autotype:: sphinxnotes.render.Value
 
 .. autoclass:: sphinxnotes.render.RawData
@@ -31,20 +32,40 @@ Value, Data, Field and Schema
 The Render Pipeline
 ===================
 
+Node
+-----
+
+.. autoclass:: sphinxnotes.render.pending_node
+
 Context
 -------
 
-.. autoclass:: sphinxnotes.render.PendingContext
+Context refers dynamic content of Jinja template. It can be:
+
+:py:class:`~sphinxnotes.render.ResolvedContext`:
+  The data we defined earlier, or any Python dict.
+
+:py:class:`~sphinxnotes.render.PendingContext`:
+   Any class that can generate this :py:class:`~sphinxnotes.render.ResolvedContext`.
+
 .. autotype:: sphinxnotes.render.ResolvedContext
-.. autoclass:: sphinxnotes.render.UnparsedData
 
-.. autoclass:: sphinxnotes.render.pending_node
+.. autoclass:: sphinxnotes.render.PendingContext
+   :members: resolve
+
+PendingContext Implementions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: sphinxnotes.render.UnparsedData
+   :show-inheritance:
 
 Extra Context
 -------------
 
 .. autoclass:: sphinxnotes.render.GlobalExtraContxt
+
 .. autoclass:: sphinxnotes.render.ParsePhaseExtraContext
+
 .. autoclass:: sphinxnotes.render.ResolvePhaseExtraContext
 
 .. autoclass:: sphinxnotes.render.ExtraContextRegistry
@@ -62,11 +83,40 @@ Template
 Pipeline
 --------
 
+Base Role Classes
+~~~~~~~~~~~~~~~~~
+
 .. autoclass:: sphinxnotes.render.BaseContextRole
-.. autoclass:: sphinxnotes.render.BaseContextDirective
+   :show-inheritance:
+
 .. autoclass:: sphinxnotes.render.BaseDataDefineRole
+   :show-inheritance:
+
+Base Directive Classes
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: sphinxnotes.render.BaseContextDirective
+   :show-inheritance:
+
 .. autoclass:: sphinxnotes.render.BaseDataDefineDirective
+   :show-inheritance:
+
 .. autoclass:: sphinxnotes.render.StrictDataDefineDirective
+   :show-inheritance:
+   :members: derive
+
+Internal Used Classes
+~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: sphinxnotes.render.pipeline.Pipeline
+   :members: process_pending_node, queue_pending_node, queue_context
+
+.. autoclass:: sphinxnotes.render.pipeline.BaseContextSource
+   :show-inheritance:
+   :members: current_context, current_template
+
+.. autoclass:: sphinxnotes.render.sources.BaseRawDataSource
+   :members: current_raw_data, current_schema
 
 Registry
 ========

docs/conf.py

@@ -130,10 +130,8 @@
     'member-order': 'bysource',
 }
 
-
 intersphinx_mapping['python'] = ('https://docs.python.org/3', None)
 intersphinx_mapping['sphinx'] = ('https://www.sphinx-doc.org/en/master', None)
 
 def setup(app):
- 
     app.add_object_type('event', 'event') # for intersphinx

src/sphinxnotes/render/ctx.py

@@ -1,11 +1,6 @@
 """
-sphinxnotes.render.ctx
-~~~~~~~~~~~~~~~~~~~~~~
-
-:copyright: Copyright 2026 by the Shengyu Zhang.
-:license: BSD, see LICENSE for details.
-
-This module wraps the :mod:`data` into context for rendering the template.
+This module wraps the :py:mod:`sphinxnote.render.data` module into context
+suitable for use with Jinja templates.
 """
 
 from typing import Any
@@ -17,6 +12,7 @@
 from .utils import Unpicklable
 
 type ResolvedContext = ParsedData | dict[str, Any]
+"""The context is """
 
 
 @dataclass
@@ -31,18 +27,17 @@ def __hash__(self) -> int:
 
 
 class PendingContext(ABC, Unpicklable, Hashable):
-    """A abstract representation of context that is not currently available.
-
-    Call :py:meth:`resolve` at the right time (depends on the implment) to get
-    context available.
-    """
+    """A abstract representation of context that is not currently available."""
 
     @abstractmethod
-    def resolve(self) -> ResolvedContext: ...
+    def resolve(self) -> ResolvedContext:
+        """This method will be called when rendering to get the available
+        :py:type:`ResolvedContext`."""
+        ...
 
 
 class PendingContextStorage:
-    """Area for temporarily storing PendingContext.
+    """Area for temporarily storing :py:class:`PendingContext`.
 
     This class is indented to resolve the problem that:
 

src/sphinxnotes/render/ctxnodes.py

@@ -20,6 +20,8 @@
 
 
 class pending_node(nodes.Element):
+    """A docutils node to be rendered."""
+
     # The context to be rendered by Jinja template.
     ctx: PendingContextRef | ResolvedContext
     # The extra context as supplement to ctx.
@@ -64,7 +66,7 @@ def __init__(
 
     def render(self, host: Host) -> None:
         """
-        The core function for rendering context to docutils nodes.
+        The core function for rendering context and template to docutils nodes.
 
         1. PendingContextRef -> PendingContext -> ResolvedContext
         2. TemplateRenderer.render(ResolvedContext) -> Markup Text (``str``)

src/sphinxnotes/render/pipeline.py

@@ -1,4 +1,4 @@
-"""
+"""pip
 sphinxnotes.render.pipeline
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -10,13 +10,13 @@
 The Pipline
 ===========
 
-1. Define context: BaseDataSource generates a :class:`pending_node`, which contains:
+1. Define context: BaseContextSource generates a :class:`pending_node`, which contains:
 
    - Context
    - Template for rendering data to markup text
    - Possible extra contexts
 
-   See also :class:`BaseDataSource`.
+   See also :class:`BaseContextSource`.
 
 2. Render data: the ``pending_node`` nodes will be rendered
    (by calling :meth:`pending_node.render`) at some point, depending on
@@ -29,7 +29,7 @@
    Phases:
 
    :``Phase.Parsing``:
-      Called by BaseDataSource ('s subclasses)
+      Called by BaseContextSource ('s subclasses)
 
    :``Phase.Parsed``:
       Called by :class:`ParsedHookTransform`.
@@ -67,22 +67,23 @@
 
 class Pipeline(ABC):
     """
-    The core class defines the pipleing of rendering :class:`pending_node`s.
+    The core class defines the pipleing of rendering
+    :py:class:`~sphinxnotes.render.pending_node`\ (s).
 
     Subclass is responsible to:
 
     - call ``queue_xxx`` to add pendin nodes into queue.
-    - override :meth:`process_pending_node` to control when a pending node gets
+    - override :py:meth:`~Pipeline.process_pending_node` to control when a pending node gets
       rendered. In this method subclass can also call ``queue_xxx`` to add more
       pending nodes.
-    - call :meth:`render_queue` to process all queued nodes and
+    - call :py:meth:`render_queue` to process all queued nodes and
       returns any that couldn't be rendered in the current phase.
 
     See Also:
 
-    - :class:`BaseDataSource`: Context source implementation and hook for Phase.Parsing
-    - :class:`ParsedHookTransform`: Built-in hook for Phase.Parsed
-    - :class:`ResolvingHookTransform`: Built-in hook for Phase.Resolving
+    - :py:class:`BaseContextSource`: Context source implementation and hook for Phase.Parsing
+    - :py:class:`ParsedHookTransform`: Built-in hook for Phase.Parsed
+    - :py:class:`ResolvingHookTransform`: Built-in hook for Phase.Resolving
     """
 
     #: Queue of pending node to be rendered.
@@ -92,18 +93,28 @@ class Pipeline(ABC):
 
     def process_pending_node(self, n: pending_node) -> bool:
         """
-        You can add hooks to pending node here.
+        This method is called when it is the pending node's turn to be rendered.
 
         Return ``true`` if you want to render the pending node *now*,
-        otherwise it will be inserted to doctree directly andwaiting to later
-        rendering
+        otherwise it will be inserted to doctree directly and waiting to later
+        rendering (and this method will be called again.).
+
+        You can add hooks to pending node here. or call :py:meth:`~Pipeline.queue_pending_node`
+        to. You are responsible for inserting it into the doctree themselves if
+        the node is created by the yourself.
+
+        .. note::
+
+           Please always call ``super().process_pending_node(n)`` to ensure the
+           extension functions properly.
         """
         ...
 
     """Helper method for subclasses."""
 
     @final
     def queue_pending_node(self, n: pending_node) -> None:
+        """Push a new pending_node to the render queue."""
         if not self._q:
             self._q = []
         self._q.append(n)
@@ -112,6 +123,7 @@ def queue_pending_node(self, n: pending_node) -> None:
     def queue_context(
         self, ctx: PendingContext | ResolvedContext, tmpl: Template
     ) -> pending_node:
+        """A helper method of :py:meth:`Pipeline.queue_pending_node`."""
         pending = pending_node(ctx, tmpl)
         self.queue_pending_node(pending)
         return pending
@@ -121,8 +133,9 @@ def render_queue(self) -> list[pending_node]:
         """
         Try rendering all pending nodes in queue.
 
-        If the timing(Phase) is ok, :class:`pending_node` will be rendered
-        (pending.rendered = True); otherwise, the pending node is unchanged.
+        If the timing(Phase) is ok, :py:class:`sphinxnotes.render.pending_node`
+        will be rendered (pending.rendered = True); otherwise, the pending node
+        is unchanged.
 
         If the pending node is already inserted to document, it will not be return.
         And the corrsponding rendered node will replace it too.
@@ -176,9 +189,9 @@ class BaseContextSource(Pipeline):
     pipeline.
 
     This class also responsible to render context in Phase.Parsing. So the final
-    implementations MUST be subclass of :class:`SphinxDirective` or
-    :class:`SphinxRole`, which provide the execution context and interface for
-    processing reStructuredText markup.
+    implementations MUST be subclass of :py:class:`~sphinx.util.docutils.SphinxDirective`
+    or :py:class:`~sphinx.util.docutils.SphinxRole`, which provide the execution
+    context and interface forrprocessing reStructuredText markup.
     """
 
     """Methods to be implemented."""
@@ -217,6 +230,13 @@ def process_pending_node(self, n: pending_node) -> bool:
 
 
 class BaseContextDirective(BaseContextSource, SphinxDirective):
+    """This class generates :py:meth:`sphinxnotes.render.pending_node` in
+    ``SphinxDirective.run`` method and make sure it can be correctly rendered.
+
+    User should implement ``current_context`` and ``current_template`` methods
+    for providing the construct parameters of pending_node.
+    """
+
     @override
     def run(self) -> list[nodes.Node]:
         self.queue_context(self.current_context(), self.current_template())
@@ -232,6 +252,13 @@ def run(self) -> list[nodes.Node]:
 
 
 class BaseContextRole(BaseContextSource, SphinxRole):
+    """This class extends generates :py:meth:`sphinxnotes.render.pending_node` in
+    ``SphinxRole.run`` method and make sure it can be correctly rendered.
+
+    User should implement ``current_context`` and ``current_template`` methods
+    for providing the construct parameters of pending_node.
+    """
+
     @override
     def process_pending_node(self, n: pending_node) -> bool:
         n.inline = True

src/sphinxnotes/render/sources.py

@@ -22,7 +22,10 @@
 
 @dataclass
 class UnparsedData(PendingContext):
-    """A implementation of PendingContext, contains raw data and its schema."""
+    """A pending context which contains raw data and its schema.
+
+    Raw data will be parsed when calling ``resolve``.
+    """
 
     raw: RawData
     schema: Schema
@@ -44,10 +47,15 @@ class BaseRawDataSource(BaseContextSource):
     """Methods to be implemented."""
 
     @abstractmethod
-    def current_raw_data(self) -> RawData: ...
+    def current_raw_data(self) -> RawData:
+        """Return the raw data to be rendered.
+        User **must not** override ``current_context`` method of this class."""
+        ...
 
     @abstractmethod
-    def current_schema(self) -> Schema: ...
+    def current_schema(self) -> Schema:
+        """Return the schema of raw data.
+        User **must not** override ``current_context`` method of this class."""
 
     """Methods to be overrided."""
 
@@ -57,6 +65,8 @@ def current_context(self) -> PendingContext | ResolvedContext:
 
 
 class BaseDataDefineDirective(BaseRawDataSource, BaseContextDirective):
+    """User is responsible to implemente ``current_schema`` method."""
+
     @override
     def current_raw_data(self) -> RawData:
         return RawData(
@@ -90,6 +100,13 @@ def current_schema(self) -> Schema:
     def derive(
         cls, name: str, schema: Schema, tmpl: Template
     ) -> type['StrictDataDefineDirective']:
+        """Dynamically derive a new directive class from schema and template.
+
+        This method generates a new ``StrictDataDefineDirective`` subclass with
+        the given schema and template. It automatically sets the appropriate
+        argument counts, option specifications, and content handling based on
+        the schema definition.
+        """
         if not schema.name:
             required_arguments = 0
             optional_arguments = 0