sphinxnotes-render 1.0b3__tar.gz → 1.0b4__tar.gz

{sphinxnotes_render-1.0b3 → sphinxnotes_render-1.0b4}/.cruft.json

@@ -8,7 +8,7 @@
       "name": "render",
       "full_name": "sphinxnotes-render",
       "author": "Shengyu Zhang",
-      "description": "A framework to define, constrain, and render data in Sphinx documentation",
+      "description": "Define, constrain, and render data in Sphinx documentation",
       "version": "1.0a0",
       "github_owner": "sphinx-notes",
       "github_repo": "data",

{sphinxnotes_render-1.0b3/src/sphinxnotes_render.egg-info → sphinxnotes_render-1.0b4}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: sphinxnotes-render
-Version: 1.0b3
-Summary: A framework to define, constrain, and render data in Sphinx documentation
+Version: 1.0b4
+Summary: Define, constrain, and render data in Sphinx documentation
 Author: Shengyu Zhang
 Maintainer: Shengyu Zhang
 License-Expression: BSD-3-Clause
 Project-URL: homepage, https://sphinx.silverrainz.me/render
 Project-URL: documentation, https://sphinx.silverrainz.me/render
-Project-URL: repository, https://github.com/sphinx-notes/data
+Project-URL: repository, https://github.com/sphinx-notes/render
 Project-URL: changelog, https://sphinx.silverrainz.me/render/changelog.html
-Project-URL: tracker, https://github.com/sphinx-notes/data/issues
+Project-URL: tracker, https://github.com/sphinx-notes/render/issues
 Keywords: sphinx,extension,documentation,sphinxnotes
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Plugins
@@ -24,6 +24,7 @@ Requires-Python: >=3.12
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: Sphinx>=7.0
+Requires-Dist: Jinja2
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
@@ -32,6 +33,7 @@ Requires-Dist: ruff>=0.11.10; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
+Requires-Dist: schema; extra == "test"
 Provides-Extra: docs
 Requires-Dist: furo; extra == "docs"
 Requires-Dist: sphinx_design; extra == "docs"
@@ -42,7 +44,9 @@ Requires-Dist: sphinxext-opengraph; extra == "docs"
 Requires-Dist: sphinx-last-updated-by-git; extra == "docs"
 Requires-Dist: sphinxnotes-project; extra == "docs"
 Requires-Dist: sphinxnotes-comboroles; extra == "docs"
-Requires-Dist: sphinxnotes-data; extra == "docs"
+Requires-Dist: schema; extra == "docs"
+Provides-Extra: ext
+Requires-Dist: schema; extra == "ext"
 Dynamic: license-file
 
 .. This file is generated from sphinx-notes/cookiecutter.
@@ -67,7 +71,7 @@ sphinxnotes-render
 
 |docs| |license| |pypi| |download|
 
-A framework to define, constrain, and render data in Sphinx documentation.
+Define, constrain, and render data in Sphinx documentation.
 
 .. INTRODUCTION START 
    (MUST written in standard reStructuredText, without Sphinx stuff)

{sphinxnotes_render-1.0b3 → sphinxnotes_render-1.0b4}/README.rst

@@ -20,7 +20,7 @@ sphinxnotes-render
 
 |docs| |license| |pypi| |download|
 
-A framework to define, constrain, and render data in Sphinx documentation.
+Define, constrain, and render data in Sphinx documentation.
 
 .. INTRODUCTION START 
    (MUST written in standard reStructuredText, without Sphinx stuff)

{sphinxnotes_render-1.0b3 → sphinxnotes_render-1.0b4}/docs/api.rst

@@ -2,39 +2,52 @@
 API References
 ==============
 
-The Render Pipeline
-===================
+.. _api-directives:
+.. _api-roles:
 
-The pipeline defines how nodes carrying data are generated and when they are
-rendered as part of the document.
+Roles and Directives
+====================
 
-1. Generation: :py:class:`~sphinxnotes.render.BaseContextRole`,
-   :py:class:`~sphinxnotes.render.BaseContextDirective` and their subclasses
-   create :py:class:`~sphinxnotes.render.pending_node` on document parsing,
-   and the node will be inserted to the document tree. The node contains:
+.. seealso::
 
-   - :ref:`context`, the dynamic content of a Jinja template
+   For a minimal end-to-end example of creating your own directive, start with
+   :ref:`ext-directives`.
 
-   - :py:class:`~sphinxnotes.render.Template`,
-      the Jinja template for rendering context to markup text
-      (reStructuredText or Markdown)
+Base Role Classes
+-----------------
 
-2. Render: the ``pending_node`` node will be rendered at the appropriate
-   :py:class:`~sphinxnotes.render.Phase`, depending on
-   :py:attr:`~sphinxnotes.render.pending_node.template.phase`.
+.. autoclass:: sphinxnotes.render.BaseContextRole
+   :show-inheritance:
+   :members: process_pending_node, queue_pending_node, queue_context, current_context, current_template
 
-For a task-oriented explanation of template variables, extra context, and phase
-selection, see :doc:`tmpl`.
+.. autoclass:: sphinxnotes.render.BaseDataDefineRole
+   :show-inheritance:
+   :members: process_pending_node, queue_pending_node, queue_context, current_schema, current_template
+
+Base Directive Classes
+----------------------
+
+.. autoclass:: sphinxnotes.render.BaseContextDirective
+   :show-inheritance:
+   :members: process_pending_node, queue_pending_node, queue_context, current_raw_data, current_context, current_template
+
+.. autoclass:: sphinxnotes.render.BaseDataDefineDirective
+   :show-inheritance:
+   :members: process_pending_node, queue_pending_node, queue_context, current_raw_data, current_schema, current_template
+
+.. autoclass:: sphinxnotes.render.StrictDataDefineDirective
+   :show-inheritance:
+   :members: derive
 
 Node
------
+=====
 
 .. autoclass:: sphinxnotes.render.pending_node
 
-.. _context:
+.. _api-context:
 
 Context
--------
+=======
 
 Context refers to the dynamic content of a Jinja template. It can be:
 
@@ -57,7 +70,7 @@ Context refers to the dynamic content of a Jinja template. It can be:
    :members: resolve
 
 ``PendingContext`` Implementations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------
 
 .. autoclass:: sphinxnotes.render.UnparsedData
    :show-inheritance:
@@ -65,7 +78,7 @@ Context refers to the dynamic content of a Jinja template. It can be:
 .. _extractx:
 
 Template
---------
+========
 
 See :doc:`tmpl` for the higher-level guide.
 
@@ -76,51 +89,33 @@ See :doc:`tmpl` for the higher-level guide.
    :members:
 
 Extra Context
--------------
-
-See :doc:`tmpl` for built-in extra-context names such as ``_doc`` and
-``_sphinx``, plus usage examples.
-
-.. autoclass:: sphinxnotes.render.GlobalExtraContxt
+=============
 
-.. autoclass:: sphinxnotes.render.ParsePhaseExtraContext
-
-.. autoclass:: sphinxnotes.render.ResolvePhaseExtraContext
-
-.. autoclass:: sphinxnotes.render.ExtraContextRegistry
-   :members:
+See :doc:`tmpl` for built-in extra-context names such as ``doc`` and
+``sphinx``, plus usage examples.
 
+.. autodecorator:: sphinxnotes.render.extra_context
 
-Base Roles and Directives
--------------------------
-
-For a minimal end-to-end example of a custom directive, start with :doc:`usage`.
-
-Base Role Classes
-~~~~~~~~~~~~~~~~~
-
-.. autoclass:: sphinxnotes.render.BaseContextRole
-   :show-inheritance:
-   :members: process_pending_node, queue_pending_node, queue_context, current_context, current_template
+.. autoclass:: sphinxnotes.render.ParsingPhaseExtraContext
+   :members: phase, generate
+   :undoc-members:
 
-.. autoclass:: sphinxnotes.render.BaseDataDefineRole
-   :show-inheritance:
-   :members: process_pending_node, queue_pending_node, queue_context, current_schema, current_template
+.. autoclass:: sphinxnotes.render.ParsedPhaseExtraContext
+   :members: phase, generate
+   :undoc-members:
 
-Base Directive Classes
-~~~~~~~~~~~~~~~~~~~~~~
+.. autoclass:: sphinxnotes.render.ResolvingPhaseExtraContext
+   :members: phase, generate
+   :undoc-members:
 
-.. autoclass:: sphinxnotes.render.BaseContextDirective
-   :show-inheritance:
-   :members: process_pending_node, queue_pending_node, queue_context, current_context, current_template
+.. autoclass:: sphinxnotes.render.GlobalExtraContext
+   :members: phase, generate
+   :undoc-members:
 
-.. autoclass:: sphinxnotes.render.BaseDataDefineDirective
-   :show-inheritance:
-   :members: process_pending_node, queue_pending_node, queue_context, current_schema, current_template
+Filters
+=======
 
-.. autoclass:: sphinxnotes.render.StrictDataDefineDirective
-   :show-inheritance:
-   :members: derive
+.. autodecorator:: sphinxnotes.render.filter
 
 Data, Field and Schema
 ======================
@@ -161,4 +156,3 @@ or add new extra context) by adding new items to
 .. autoclass:: sphinxnotes.render.Registry
 
    .. autoproperty:: data
-   .. autoproperty:: extra_context

{sphinxnotes_render-1.0b3 → sphinxnotes_render-1.0b4}/docs/conf.py

@@ -122,23 +122,46 @@ import sys
 sys.path.insert(0, os.path.abspath('../src/'))
 extensions.append('sphinxnotes.render')
 
-extensions.append('sphinxnotes.data')
-
 # CUSTOM CONFIGURATION
 
+extensions.append('sphinxnotes.render.ext')
+
+# [example config start]
+render_ext_data_define_directives = {
+   'cat': {
+       'schema': {
+           'name': 'str, required',
+           'attrs': {
+               'color': 'str',
+           },
+           'content': 'str, required'
+       },
+       'template': {
+           'text': '\n'.join([
+               'Hi human! I am a cat named {{ name }}, I have {{ color }} fur.',
+               '',
+               '{{ content }}.',
+           ]),
+       },
+   },
+}
+# [example config end]
+
 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)
-intersphinx_mapping['data'] = ('https://sphinx.silverrainz.me/data', None)
 
-ctxdir_usage_example_path = os.path.abspath('../tests/roots/test-ctxdir-usage')
+test_roots = os.path.abspath('../tests/roots')
 
 def setup(app):
     app.add_object_type('event', 'event') # for intersphinx
 
-    sys.path.insert(0, ctxdir_usage_example_path)
-    from conf import setup as setup_ctxdir_usage_example
-    setup_ctxdir_usage_example(app)
+    sys.path.insert(0, test_roots)
+    __import__('test-extra-context.conf').conf.setup(app)
+    __import__('test-base-context-directive-example.conf').conf.setup(app)
+    __import__('test-base-data-define-directive-example.conf').conf.setup(app)
+    __import__('test-strict-data-define-directive-example.conf').conf.setup(app)
+    __import__('test-filter-example.conf').conf.setup(app)

sphinxnotes_render-1.0b4/docs/conf.rst

@@ -0,0 +1,31 @@
+=============
+Configuration
+=============
+
+The extension provides the following configuration:
+
+.. autoconfval:: render_ext_data_define_directives
+
+   A dictionary ``dict[str, directive_def]`` for creating custom directives for
+   data definition.
+
+   The ``str`` key is the name of the directive to be created;
+   The ``directive_def`` value is a ``dict`` with the following keys:
+
+   - ``schema`` (dict): Schema definition, works same as the
+     :rst:dir:`data.schema` directive, which has the following keys:
+
+     - ``name`` (str, optional): same as the directive argument
+     - ``attr`` (dict, can be empty): same as the directive options
+     - ``content`` (str, optional): same as the directive content
+
+   - ``template`` (dict): Template definition, works same as the
+     :rst:dir:`data.template` directive, which has the following keys:
+
+     - ``text`` (str): the Jinja2 template text.
+     - ``on`` (str, optional): same as :rst:dir:`data.template:on`
+     - ``debug`` (bool, optional): same as :rst:dir:`data.template:debug`
+     - ``extra`` (list[str], optional): same as :rst:dir:`data.template:extra`
+
+   See :ref:`usage-custom-directive` for example.
+

{sphinxnotes_render-1.0b3 → sphinxnotes_render-1.0b4}/docs/dsl.rst

@@ -180,61 +180,3 @@ DSL                 Input     Result
 ``int, sep by ':'`` ``1:2:3`` :py:`[1, 2, 3]`
 =================== ========= ================
 
-Extending the FDL
-=================
-
-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`.
-
-.. _add-custom-types:
-
-Adding Custom Types
--------------------
-
-Use :meth:`~sphinxnotes.render.data.REGISTRY.add_type` method of
-:data:`sphinxnotes.render.REGISTRY` to add a new type:
-
->>> 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)
->>> Field.from_dsl('color').parse('255;0;0')
-(255, 0, 0)
-
-.. _add-custom-flags:
-
-Adding Custom Flags
--------------------
-
-Use :meth:`~sphinxnotes.render.data.Registry.add_flag` method of
-:data:`sphinxnotes.render.REGISTRY` to add a new flag:
-
->>> from sphinxnotes.render import REGISTRY
->>> REGISTRY.data.add_flag('unique', default=False)
->>> field = Field.from_dsl('int, unique')
->>> field.unique
-True
-
-.. _add-custom-by-options:
-
-Adding Custom By-Options
-------------------------
-
-Use :meth:`~sphinxnotes.render.data.Registry.add_by_option` method of
-:data:`sphinxnotes.render.REGISTRY` to add a new by-option:
-
->>> from sphinxnotes.render import REGISTRY
->>> REGISTRY.data.add_by_option('group', str)
->>> field = Field.from_dsl('str, group by size')
->>> field.group
-'size'
->>> REGISTRY.data.add_by_option('index', str, store='append')
->>> field = Field.from_dsl('str, index by month, index by year')
->>> field.index
-['month', 'year']

sphinxnotes_render-1.0b4/docs/ext.rst

@@ -0,0 +1,252 @@
+=========
+Extending
+=========
+
+Extending the FDL
+=================
+
+You can extend the :doc:`dsl` by registering custom types, flags, and by-options
+through the :py:attr:`~sphinxnotes.render.Registry.data` attribute of
+:py:data:`sphinxnotes.render.REGISTRY`.
+
+.. _add-custom-types:
+
+Adding Custom Types
+-------------------
+
+Use :py:meth:`~sphinxnotes.render.data.REGISTRY.add_type` method of
+:py:data:`sphinxnotes.render.REGISTRY` to add a new type:
+
+>>> from sphinxnotes.render import REGISTRY, Field
+>>> 
+>>> 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)
+>>> Field.from_dsl('color').parse('255;0;0')
+(255, 0, 0)
+
+.. _add-custom-flags:
+
+Adding Custom Flags
+-------------------
+
+Use :py:meth:`~sphinxnotes.render.data.Registry.add_flag` method of
+:py:data:`sphinxnotes.render.REGISTRY` to add a new flag:
+
+>>> from sphinxnotes.render import REGISTRY, Field
+>>> REGISTRY.data.add_flag('unique', default=False)
+>>> field = Field.from_dsl('int, unique')
+>>> field.unique
+True
+
+.. _add-custom-by-options:
+
+Adding Custom By-Options
+------------------------
+
+Use :py:meth:`~sphinxnotes.render.data.Registry.add_by_option` method of
+:py:data:`sphinxnotes.render.REGISTRY` to add a new by-option:
+
+>>> from sphinxnotes.render import REGISTRY, Field
+>>> REGISTRY.data.add_by_option('group', str)
+>>> field = Field.from_dsl('str, group by size')
+>>> field.group
+'size'
+>>> REGISTRY.data.add_by_option('index', str, store='append')
+>>> field = Field.from_dsl('str, index by month, index by year')
+>>> field.index
+['month', 'year']
+
+.. _ext-extra-context:
+
+Extending Extra Contexts
+========================
+
+Extra contexts are registered by a
+:py:deco:`sphinxnotes.render.extra_context` class decorator.
+
+The decorated class must be one of the following classes:
+:py:class:`~sphinxnotes.render.ParsingPhaseExtraContext`,
+:py:class:`~sphinxnotes.render.ParsedPhaseExtraContext`,
+:py:class:`~sphinxnotes.render.ResolvingPhaseExtraContext`,
+:py:class:`~sphinxnotes.render.GlobalExtraContext`.
+
+.. literalinclude:: ../tests/roots/test-extra-context/conf.py
+   :language: python
+   :start-after: [literalinclude start]
+   :end-before: [literalinclude end]
+
+.. dropdown:: :file:`cat.json`
+
+   .. literalinclude:: ../tests/roots/test-extra-context/cat.json
+
+.. example::
+   :style: grid
+
+   .. data.render::
+      :extra: cat
+
+      {{ load_extra('cat').name }}
+
+.. _ext-filters:
+
+Extending ilters
+=================
+
+Template filters are registered by a
+:py:deco:`sphinxnotes.render.filter` function decorator.
+
+The decorated function takes a :py:class:`sphinx.environment.BuildEnvironment`
+as argument and returns a filter function.
+
+.. note::
+
+   The decorator is used to **decorate the filter function factory, NOT
+   the filter function itself**.
+
+.. literalinclude:: ../tests/roots/test-filter-example/conf.py
+   :language: python
+   :start-after: [literalinclude start]
+   :end-before: [literalinclude end]
+
+.. example::
+   :style: grid
+
+   .. data.render::
+
+      {{ "Hello world" | catify }}
+
+.. _ext-directives:
+.. _ext-roles:
+
+Extending Directives/Roles
+==========================
+
+.. tip::
+
+   Before reading this documentation, please refer to
+   :external+sphinx:doc:`development/tutorials/extending_syntax`.
+   See how to extend :py:class:`SphinxDirective` and :py:class:`SphinxRole`.
+
+All of the classes listed in :ref:`api-directives` are subclassed from the
+internal ``sphinxnotes.render.Pipeline`` class, which is responsible to generate
+the dedicated :py:class:`node <sphinxnotes.render.pending_node>` that
+carries a :ref:`context` and a :py:class:`~sphinxnotes.render.Template`.
+
+At the appropriate :ref:`render-phases`, the node will be rendered into markup
+text, usually reStructuredText. The rendered text is then parsed again by
+Sphinx and inserted into the document.
+
+.. seealso::
+
+   - :doc:`tmpl` for template variables, phases, and extra context
+   - :doc:`dsl` for the field description language used by
+     :py:class:`~sphinxnotes.render.Field` and
+     :py:class:`~sphinxnotes.render.Schema`
+   - Implementations of :parsed_literal:`sphinxnotes-render.ext__`
+     and :parsed_literal:`sphinxnotes-any__`.
+
+   __ https://github.com/sphinx-notes/render/tree/master/src/sphinxnotes/render/ext
+   __ https://github.com/sphinx-notes/any
+
+Subclassing :py:class:`~sphinxnotes.render.BaseContextDirective`
+----------------------------------------------------------------
+
+Now we have a quick example to help you get Started.
+:external+sphinx:doc:`Create a Sphinx documentation <tutorial/getting-started>`
+with the following ``conf.py``:
+
+.. literalinclude:: ../tests/roots/test-base-context-directive-example/conf.py
+
+This is the smallest useful extension built on top of ``sphinxnotes.render``:
+
+- it defines a mimi-dedicated directive by subclassing
+  :py:class:`~sphinxnotes.render.BaseContextDirective`
+- it returns a :py:class:`~sphinxnotes.render.ResolvedContext` object from
+  ``current_context()``
+- it returns a :py:class:`~sphinxnotes.render.Template` from
+  ``current_template()``
+- the template is rendered in the default
+  :py:data:`~sphinxnotes.render.Phase.Parsing` phase
+
+Now use the directive in your document:
+
+.. example::
+   :style: grid
+
+   .. mimi::
+ 
+Subclassing :py:class:`~sphinxnotes.render.BaseDataDefineDirective`
+-------------------------------------------------------------------
+
+``BaseDataDefineDirective`` is higher level of API than ``BaseContextDirective``.
+You no longer need to implement the ``current_context`` methods; instead,
+implement the :py:meth:`~sphinxnotes.render.BaseDataDefineDirective.current_schema`
+method.
+
+Here's an example:
+
+.. literalinclude:: ../tests/roots/test-base-data-define-directive-example/conf.py
+
+Key differences from ``BaseContextDirective``:
+
+- The directive automatically generates :py:class:`~sphinxnotes.render.RawData`
+  (from directive's arguments, options, and content, by method
+  :py:meth:`~sphinxnotes.render.BaseDataDefineDirective.current_raw_data`).
+- The generated RawData are parsed to :py:class:`~sphinxnotes.render.ParsedData`
+  according to the :py:class:`~sphinxnotes.render.Schema` returned from
+  :py:meth:`~sphinxnotes.render.BaseDataDefineDirective.current_schema` method.
+
+  .. tip::
+
+     Internally, the ``ParsedData`` is returned by ``current_context``, so
+     we do not need to implement it.
+
+- The the fields of schema are generated from :doc:`dsl` which restricted the
+  ``color`` must be an space-separated list, and ``birth`` must be a integer.
+- The ``current_template`` still returns a Jinja template, but it uses more fancy
+  syntax.
+
+Use the directive in your document:
+
+.. example::
+   :style: grid
+
+   .. cat2:: mimi
+      :color: black and brown
+      :birth: 2025
+
+      I like fish!
+
+Subclassing :py:class:`~sphinxnotes.render.StrictDataDefineDirective`
+----------------------------------------------------------------------
+
+``StrictDataDefineDirective`` is an even higher-level API built on top of
+``BaseDataDefineDirective``. It automatically handles ``SphinxDirective``'s members
+from your :py:class:`~sphinxnotes.render.Schema`, so you don't need to manually
+set:
+
+- ``required_arguments`` / ``optional_arguments`` - derived from ``Schema.name``
+- ``option_spec`` - derived from ``Schema.attrs`` 
+- ``has_content`` - derived from ``Schema.content``
+
+You no longer need to manually create subclasses, simply pass ``schema`` and
+``template`` to :py:meth:`~sphinxnotes.render.StrictDataDefineDirective.derive`
+method:
+
+.. literalinclude:: ../tests/roots/test-strict-data-define-directive-example/conf.py
+
+Use the directive in your document:
+
+.. example::
+   :style: grid
+
+   .. cat3:: mimi
+      :color: black and brown
+      :birth: 2025
+
+      I like fish!