docs: Add DSL documentation

Co-authored-by: MiniMax-M2.5 <minimax-cn-coding-plan@minimax.io>
Co-authored-by: opencode <opencode@anomaly.co>

Author: 3 people

docs/api.rst

@@ -5,3 +5,15 @@ API Reference
 .. note:: WIP
 
 .. automodule:: sphinxnotes.render.pipeline
+
+.. autoclass:: sphinxnotes.render.Registry
+
+    .. autoproperty:: data
+    .. autoproperty:: extra_context
+
+.. autoclass:: sphinxnotes.render.data.Registry
+   
+   .. automethod:: add_type
+   .. automethod:: add_form
+   .. automethod:: add_flag
+   .. automethod:: add_by_option

docs/dsl.rst

@@ -0,0 +1,199 @@
+=====================
+Field Declaration DSL
+=====================
+
+.. default-domain:: py
+.. highlight:: 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
+one or more **modifiers** separated by commas (``,``).
+
+Syntax
+======
+
+.. productionlist::
+   dsl          : modifier ("," modifier)*
+   modifier     : type_modifier | container_modifier | flag | by_option
+
+There are four categories of modifiers:
+
+:Type:      Specifies the element type (scalar value)
+:Form:      Specifies a container type with element type
+:Flag:      A boolean option (either on or off)
+:By-Option: A key-value option
+
+Type
+====
+
+A type modifier specifies the data type of a single (scalar) value.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Modifier
+     - Type
+     - Aliases
+     - Description
+   * - ``bool``
+     - :py:class:`bool`
+     - ``flag``
+     - Boolean: ``true``/``yes``/``1``/``on``/``y`` → True, ``false``/``no``/``0``/``off``/``n`` → False
+   * - ``int``
+     - :py:class:`int`
+     - ``integer``
+     - Integer
+   * - ``float``
+     - :py:class:`float`
+     - ``number``, ``num``
+     - Floating-point number
+   * - ``str``
+     - :py:class:`str`
+     - ``string``
+     - String. If looks like a Python literal (e.g., ``"hello"``), it's parsed accordingly.
+
+Examples::
+
+    int          -> "42"     becomes 42
+    str          -> "hello"  becomes "hello"
+
+Form
+====
+
+A form modifier specifies a container type with its element type, using
+``<form> of <type>`` syntax.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Modifier
+     - Container
+     - Separator
+     - Description
+   * - ``list of <type>``
+     - :py:class:`list`
+     - ``,``
+     - Comma-separated list
+   * - ``lines of <type>``
+     - :py:class:`list`
+     - ``\n``
+     - Newline-separated list
+   * - ``words of <type>``
+     - :py:class:`list`
+     - whitespace
+     - Whitespace-separated list
+   * - ``set of <type>``
+     - :py:class:`set`
+     - whitespace
+     - Whitespace-separated set (unique values)
+
+Examples::
+
+    list of int       -> "1, 2, 3"    becomes [1, 2, 3]
+    lines of str      -> "a\nb"       becomes ['a', 'b']
+    words of str      -> "a   b c"    becomes ['a', 'b', 'c']
+
+Flag
+====
+
+A flag is a boolean modifier that can be either on or off.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Modifier
+     - Aliases
+     - Default
+     - Description
+   * - ``required``
+     - ``require``, ``req``
+     - ``False``
+     - Field must have a value
+
+Examples::
+
+    int, required
+
+By-Option
+=========
+
+A by-option is a key-value modifier with the syntax ``<name> by <value>``.
+
+Built-in by-options:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Modifier
+     - Type
+     - Description
+   * - ``sep by '<sep>'``
+     - :py:class:`str`
+     - Custom separator for container values. Implies list if no container specified.
+
+Examples::
+
+    list sep by '|'
+    int sep by ':'           -> "1:2:3"    becomes [1, 2, 3]
+
+Extending the DSL
+=================
+
+You can extend the DSL by registering custom types, flags, and by-options
+through the :attr:`sphinxnotes.render.Registry.data` attribute of
+:class:`sphinxnotes.render.Registry`.
+
+Adding Custom Types
+-------------------
+
+Use :meth:`sphinxnotes.render.Registry.data.add_type` to add a new type:
+
+.. code-block:: python
+
+    from sphinxnotes.render import Registry
+
+    def parse_color(v: str):
+        return tuple(int(x) for x in v.split(','))
+
+    def color_to_str(v):
+        return ','.join(str(x) for x in v)
+
+    Registry.data.add_type('color', tuple, parse_color, color_to_str)
+
+Usage::
+
+    color          -> "255,0,0"    becomes (255, 0, 0)
+
+Adding Custom Flags
+-------------------
+
+Use :attr:`sphinxnotes.render.Registry.data` to add a new type:
+
+.. code-block:: python
+
+    from sphinxnotes.render import Registry
+
+    Registry.data.add_flag('unique', default=False)
+
+Usage::
+
+    int, unique
+
+Adding Custom By-Options
+------------------------
+
+Use :meth:`sphinxnotes.render.Registry.data`:
+
+.. code-block:: python
+
+    from sphinxnotes.render import Registry
+
+    Registry.data.add_by_option('group', str)
+
+    # For options that can be specified multiple times:
+    Registry.data.add_by_option('index', str, store='append')
+
+Usage::
+
+    int, group by foo
+    int, index by year, index by month

docs/index.rst

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