docs: Autodoc improvements

Author: SilverRainZ

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.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.ResolvePhaseExtraContext
+
 .. autoclass:: sphinxnotes.render.ExtraContextRegistry
+   :members:
 
 Template
 --------
 
 .. autoclass:: sphinxnotes.render.Template
+   :members:
+
 .. autoclass:: sphinxnotes.render.Phase
+   :members:
 
 Pipeline
 --------

docs/conf.py

@@ -123,7 +123,17 @@
 
 # CUSTOM CONFIGURATION
 
-_ = extensions.pop() # no need to load extension
-primary_domain = 'py'
-
 extensions.append('sphinx.ext.doctest')
+extensions.append('sphinxnotes.data')
+
+autodoc_default_options = {
+    '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

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
 ======
 
@@ -46,6 +36,17 @@ Syntax
    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]
+
+
 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`.
 

src/sphinxnotes/render/__init__.py

@@ -28,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,
+    ResolvePhaseExtraContext,
+)
 from .pipeline import BaseContextRole, BaseContextDirective
 from .sources import (
     UnparsedData,
@@ -56,6 +62,9 @@
     'Host',
     'PendingContext',
     'ResolvedContext',
+    'GlobalExtraContxt',
+    'ParsePhaseExtraContext',
+    'ResolvePhaseExtraContext',
     'pending_node',
     'BaseContextRole',
     'BaseContextDirective',

src/sphinxnotes/render/ctx.py

@@ -33,7 +33,7 @@ def __hash__(self) -> int:
 class PendingContext(ABC, Unpicklable, Hashable):
     """A abstract representation of context that is not currently available.
 
-    Call :meth:`resolve` at the right time (depends on the implment) to get
+    Call :py:meth:`resolve` at the right time (depends on the implment) to get
     context available.
     """
 
@@ -52,7 +52,7 @@ class PendingContextStorage:
 
     This class maintains a mapping from :class:`PendingContextRef` -> :cls:`PendingContext`.
     ``pending_node`` owns the ``PendingContextRef``, and can retrieve the context
-    by calling :meth:`retrieve`.
+    by calling :py:meth:`retrieve`.
     """
 
     _next_id: int

src/sphinxnotes/render/data.py

@@ -157,7 +157,7 @@ def add_type(
         strify: Callable[[PlainValue], str],
         aliases: list[str] = [],
     ) -> None:
-        """Register a value type for :class:`PlainValue`.
+        """Register a value type for :py:class:`PlainValue`.
 
         :param name: The name for this scalar type,
                      available as a :term:`Type modifier` in the DSL
@@ -179,12 +179,12 @@ def add_form(
         self, name: str, ctype: type, sep: str, aliases: list[str] = []
     ) -> None:
         """Register an value form with its container type and separator for
-        :class:`Value`.
+        :py:class:`Value`.
 
         :param name: The name for this form, available as a :term:`Form modifier`
                      in the DSL
         :param ctype: The container type.
-                      (for now, it is :class:`list`, :class:`tuple`, or :class:`set`)
+                      (for now, it is :py:class:`list`, :py:class:`tuple`, or :py:class:`set`)
         :param sep: The separator string used to split/join values
         :param aliases: Alternative names for this form
         """
@@ -273,10 +273,10 @@ def asdict(self) -> dict[str, Any]:
         ``self.attrs`` will be automaticlly lifted to top-level context when
         there is no key conflicts. For example:
 
-        - You can access ``Data.attrs['color']`` by "{{ color }}"" instead
-        of "{{ attrs.color }}".
+        - You can access ``Data.attrs['color']`` by "{{ color }}" instead
+          of "{{ attrs.color }}".
         - You can NOT access ``Data.attrs['name']`` by "{{ name }}" cause
-        the variable name is taken by ``Data.name``.
+          the variable name is taken by ``Data.name``.
         """
         ctx = asdict(self)
         for k, v in self.attrs.items():

src/sphinxnotes/render/extractx.py

@@ -13,22 +13,29 @@
 if TYPE_CHECKING:
     from typing import Any, Callable, ClassVar
     from sphinx.application import Sphinx
-    from .render import ParseHost, TransformHost
+    from .render import ParseHost, ResolveHost
 
 
 class GlobalExtraContxt(ABC):
+    """Extra context availabled on any phase."""
+
     @abstractmethod
     def generate(self) -> Any: ...
 
 
 class ParsePhaseExtraContext(ABC):
+    """Extra context generated during the :py:class:`~Phase.Parsing` or
+    :py:class:`~Phase.Parsing` phase."""
+
     @abstractmethod
     def generate(self, host: ParseHost) -> Any: ...
 
 
-class TransformPhaseExtraContext(ABC):
+class ResolvePhaseExtraContext(ABC):
+    """Extra context generated during the :py:class:`~Phase.Resolving` phase."""
+
     @abstractmethod
-    def generate(self, host: TransformHost) -> Any: ...
+    def generate(self, host: ResolveHost) -> Any: ...
 
 
 # =======================
@@ -39,8 +46,8 @@ def generate(self, host: TransformHost) -> Any: ...
 class ExtraContextRegistry:
     names: set[str]
     parsing: dict[str, ParsePhaseExtraContext]
-    parsed: dict[str, TransformPhaseExtraContext]
-    post_transform: dict[str, TransformPhaseExtraContext]
+    parsed: dict[str, ResolvePhaseExtraContext]
+    post_transform: dict[str, ResolvePhaseExtraContext]
     global_: dict[str, GlobalExtraContxt]
 
     def __init__(self) -> None:
@@ -65,22 +72,26 @@ def _name_dedup(self, name: str) -> None:
     def add_parsing_phase_context(
         self, name: str, ctxgen: ParsePhaseExtraContext
     ) -> None:
+        """Register a extra context for :py:class:`~Phase.Parsing` phase."""
         self._name_dedup(name)
         self.parsing['_' + name] = ctxgen
 
     def add_parsed_phase_context(
-        self, name: str, ctxgen: TransformPhaseExtraContext
+        self, name: str, ctxgen: ResolvePhaseExtraContext
     ) -> None:
+        """Register a extra context for :py:class:`~Phase.Parsed` phase."""
         self._name_dedup(name)
         self.parsed['_' + name] = ctxgen
 
     def add_post_transform_phase_context(
-        self, name: str, ctxgen: TransformPhaseExtraContext
+        self, name: str, ctxgen: ResolvePhaseExtraContext
     ) -> None:
+        """Register a extra context for :py:class:`~Phase.Resolving` phase."""
         self._name_dedup(name)
         self.post_transform['_' + name] = ctxgen
 
     def add_global_context(self, name: str, ctxgen: GlobalExtraContxt):
+        """Register a extra context for :py:class:`~Phase.Resolving` phase."""
         self._name_dedup(name)
         self.global_['_' + name] = ctxgen
 
@@ -162,11 +173,11 @@ def on_parsing(self, host: ParseHost) -> None:
         for name, ctxgen in self.registry.parsing.items():
             self._safegen(name, lambda: ctxgen.generate(host))
 
-    def on_parsed(self, host: TransformHost) -> None:
+    def on_parsed(self, host: ResolveHost) -> None:
         for name, ctxgen in self.registry.parsed.items():
             self._safegen(name, lambda: ctxgen.generate(host))
 
-    def on_post_transform(self, host: TransformHost) -> None:
+    def on_resolving(self, host: ResolveHost) -> None:
         for name, ctxgen in self.registry.post_transform.items():
             self._safegen(name, lambda: ctxgen.generate(host))
 

src/sphinxnotes/render/pipeline.py

@@ -53,7 +53,7 @@
 from sphinx.transforms import SphinxTransform
 from sphinx.transforms.post_transforms import SphinxPostTransform, ReferencesResolver
 
-from .render import HostWrapper, Phase, Template, Host, ParseHost, TransformHost
+from .render import HostWrapper, Phase, Template, Host, ParseHost, ResolveHost
 from .ctx import PendingContext, ResolvedContext
 from .ctxnodes import pending_node
 from .extractx import ExtraContextGenerator
@@ -260,7 +260,7 @@ class ParsedHookTransform(SphinxTransform, Pipeline):
 
     @override
     def process_pending_node(self, n: pending_node) -> bool:
-        ExtraContextGenerator(n).on_parsed(cast(TransformHost, self))
+        ExtraContextGenerator(n).on_parsed(cast(ResolveHost, self))
         return n.template.phase == Phase.Parsed
 
     @override
@@ -278,7 +278,7 @@ class ResolvingHookTransform(SphinxPostTransform, Pipeline):
 
     @override
     def process_pending_node(self, n: pending_node) -> bool:
-        ExtraContextGenerator(n).on_post_transform(cast(TransformHost, self))
+        ExtraContextGenerator(n).on_resolving(cast(ResolveHost, self))
         return n.template.phase == Phase.Resolving
 
     @override

src/sphinxnotes/render/render.py

@@ -7,12 +7,19 @@
 
 
 class Phase(Enum):
+    """The phase of rendering template."""
+
+    #: Render template on document parsing.
     Parsing = 'parsing'
+    #: Render template immediately after document has parsed
+    #: (on Sphinx event :external:event:`doctree-read`).
     Parsed = 'parsed'
+    #: Render template immediately after all documents have resolving
+    #: (before Sphinx event :external:event:`doctree-resolved`).
     Resolving = 'resolving'
 
     @classmethod
-    def default(cls) -> 'Phase':
+    def default(cls) -> Phase:
         return cls.Parsing
 
 
@@ -22,16 +29,16 @@ class Template:
     text: str
     #: The render phase.
     phase: Phase = Phase.default()
-    #: Enable debug output (shown as :class:`nodes.system_message` in document.)
+    #: Enable debug output (shown as :py:class:`docutils.nodes.system_message` in document.)
     debug: bool = False
 
 
-# Possible render host of :meth:`pending_node.render`.
-type Host = ParseHost | TransformHost
-# Host of source parse phase (Phase.Parsing, Phase.Parsed).
+#: Possible render host of :meth:`pending_node.render`.
+type Host = ParseHost | ResolveHost
+#: Host of source parse phase (Phase.Parsing, Phase.Parsed).
 type ParseHost = SphinxDirective | SphinxRole
-# Host of source parse phase (Phase.Parsing, Phase.Parsed).
-type TransformHost = SphinxTransform
+#: Host of source parse phase (Phase.Parsing, Phase.Parsed).
+type ResolveHost = SphinxTransform
 
 
 @dataclass