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

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

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/sphinx-notes/cookiecutter",
-  "commit": "62cd96195962da3392cdc34125c95e9144a5f5ca",
+  "commit": "4c6b17aec1a4b8ddca95c4882c6bed2bc230d595",
   "checkout": null,
   "context": {
     "cookiecutter": {
@@ -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",
@@ -20,7 +20,7 @@
       "sphinx_version": "7.0",
       "development_status": "3 - Alpha",
       "_template": "https://github.com/sphinx-notes/cookiecutter",
-      "_commit": "62cd96195962da3392cdc34125c95e9144a5f5ca"
+      "_commit": "4c6b17aec1a4b8ddca95c4882c6bed2bc230d595"
     }
   },
   "directory": null

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

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: sphinxnotes-render
-Version: 1.0b2
-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,6 +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: schema; extra == "docs"
+Provides-Extra: ext
+Requires-Dist: schema; extra == "ext"
 Dynamic: license-file
 
 .. This file is generated from sphinx-notes/cookiecutter.
@@ -66,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.0b2 → 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.0b4/docs/api.rst

@@ -0,0 +1,158 @@
+==============
+API References
+==============
+
+.. _api-directives:
+.. _api-roles:
+
+Roles and Directives
+====================
+
+.. seealso::
+
+   For a minimal end-to-end example of creating your own directive, start with
+   :ref:`ext-directives`.
+
+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.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
+
+.. _api-context:
+
+Context
+=======
+
+Context refers to the dynamic content of a Jinja template. It can be:
+
+:py:class:`~sphinxnotes.render.ResolvedContext`:
+  Our dedicated data type (:py:class:`sphinxnotes.render.ParsedData`), or any
+  Python ``dict``.
+
+:py:class:`~sphinxnotes.render.PendingContext`:
+   Context that is not yet available. For example, it may contain
+   :py:class:`unparsed data <sphinxnotes.render.RawData>`,
+   remote data, and more.
+
+   :py:class:`PendingContext` can be resolved to
+   :py:class:`~sphinxnotes.render.ResolvedContext` by calling
+   :py:meth:`~sphinxnotes.render.PendingContext.resolve`.
+
+.. autotype:: sphinxnotes.render.ResolvedContext
+
+.. autoclass:: sphinxnotes.render.PendingContext
+   :members: resolve
+
+``PendingContext`` Implementations
+----------------------------------
+
+.. autoclass:: sphinxnotes.render.UnparsedData
+   :show-inheritance:
+
+.. _extractx:
+
+Template
+========
+
+See :doc:`tmpl` for the higher-level guide.
+
+.. autoclass:: sphinxnotes.render.Template
+   :members:
+
+.. autoclass:: sphinxnotes.render.Phase
+   :members:
+
+Extra Context
+=============
+
+See :doc:`tmpl` for built-in extra-context names such as ``doc`` and
+``sphinx``, plus usage examples.
+
+.. autodecorator:: sphinxnotes.render.extra_context
+
+.. autoclass:: sphinxnotes.render.ParsingPhaseExtraContext
+   :members: phase, generate
+   :undoc-members:
+
+.. autoclass:: sphinxnotes.render.ParsedPhaseExtraContext
+   :members: phase, generate
+   :undoc-members:
+
+.. autoclass:: sphinxnotes.render.ResolvingPhaseExtraContext
+   :members: phase, generate
+   :undoc-members:
+
+.. autoclass:: sphinxnotes.render.GlobalExtraContext
+   :members: phase, generate
+   :undoc-members:
+
+Filters
+=======
+
+.. autodecorator:: sphinxnotes.render.filter
+
+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:
+
+   .. autotype:: sphinxnotes.render.data.ByOptionStore
+
+Registry
+========
+
+Developers can extend this extension (for example, to support more data types
+or add new extra context) by adding new items to
+:py:class:`sphinxnotes.render.REGISTRY`.
+
+.. autodata:: sphinxnotes.render.REGISTRY
+
+.. autoclass:: sphinxnotes.render.Registry
+
+   .. autoproperty:: data

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

@@ -24,6 +24,7 @@ version = release = '1.0a0'
 extensions = [
     'sphinx.ext.githubpages',
     'sphinx.ext.doctest',
+    'sphinx.ext.viewcode',
     'sphinx_design',
     'sphinx_copybutton',
     'sphinx_last_updated_by_git',
@@ -118,12 +119,49 @@ primary_domain = 'any'
 # 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')
 
 # CUSTOM CONFIGURATION
 
-_ = extensions.pop() # no need to load extension
-primary_domain = 'py'
+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)
+
+test_roots = os.path.abspath('../tests/roots')
+
+def setup(app):
+    app.add_object_type('event', 'event') # for intersphinx
 
-extensions.append('sphinx.ext.doctest')
+    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.0b2 → sphinxnotes_render-1.0b4}/docs/dsl.rst

@@ -1,6 +1,6 @@
-=====================
-Field Declaration DSL
-=====================
+==========================
+Field Description Language
+==========================
 
 .. default-domain:: py
 .. highlight:: python
@@ -8,19 +8,9 @@ Field Declaration DSL
    :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
-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]
+The Field Description Language is a Domain Specific Language (DSL) that is used to
+define the type and structure of field values. An FDL declaration consists of
+one or more :term:`modifier` entries separated by commas (``,``).
 
 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
+==========
+
+Users can create a :class:`sphinxnotes.render.Field` from FDL and use it to parse
+strings into :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
 ====
@@ -73,7 +74,7 @@ A type modifier specifies the data type of a single (scalar) value.
    * - ``str``
      - :py:class:`str`
      - ``string``
-     - String. If looks like a Python literal (e.g., ``"hello"``), it's parsed accordingly.
+     - String. If it looks like a Python literal (e.g., ``"hello"``), it is parsed accordingly.
 
 Examples:
 
@@ -129,8 +130,8 @@ Flag
 
 A flag is a boolean modifier that can be either on or off.
 
-Every flag is available as a attribute of the :class:`Field`.
-For example, we have a "required" flag registed, we can access ``Field.required``
+Every flag is available as an attribute of the :class:`Field`.
+For example, we have a "required" flag registered, and we can access ``Field.required``
 attribute.
 
 .. list-table::
@@ -154,8 +155,8 @@ By-Option
 
 A by-option is a key-value modifier with the syntax ``<name> by <value>``.
 
-Every by-option is available as a attribute of the :class:`Field`.
-For example, we have a "sep" flag registed, we can get the value of separator
+Every by-option is available as an attribute of the :class:`Field`.
+For example, we have a "sep" by-option registered, and we can get the separator
 from ``Field.sep`` attribute.
 
 Built-in by-options:
@@ -179,61 +180,3 @@ DSL                 Input     Result
 ``int, sep by ':'`` ``1:2:3`` :py:`[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
-: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 type:
-
->>> 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']