Merge pull request #10 from sphinx-notes/merge-data-back

Merge `sphinxnotes-data` back

Author: SilverRainZ

.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",

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)

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
+-----------------
+
+.. 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
+----------------------
 
-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.BaseContextDirective
+   :show-inheritance:
+   :members: process_pending_node, queue_pending_node, queue_context, current_raw_data, current_context, current_template
 
-For a task-oriented explanation of template variables, extra context, and phase
-selection, see :doc:`tmpl`.
+.. 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,15 +70,15 @@ Context refers to the dynamic content of a Jinja template. It can be:
    :members: resolve
 
 ``PendingContext`` Implementations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------
 
 .. autoclass:: sphinxnotes.render.UnparsedData
    :show-inheritance:
 
 .. _extractx:
 
 Template
---------
+========
 
 See :doc:`tmpl` for the higher-level guide.
 
@@ -76,12 +89,12 @@ 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.
 
-.. autofunction:: sphinxnotes.render.extra_context
+.. autodecorator:: sphinxnotes.render.extra_context
 
 .. autoclass:: sphinxnotes.render.ParsingPhaseExtraContext
    :members: phase, generate
@@ -99,36 +112,10 @@ See :doc:`tmpl` for built-in extra-context names such as ``doc`` and
    :members: phase, generate
    :undoc-members:
 
-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.BaseDataDefineRole
-   :show-inheritance:
-   :members: process_pending_node, queue_pending_node, queue_context, current_schema, current_template
-
-Base Directive Classes
-~~~~~~~~~~~~~~~~~~~~~~
+Filters
+=======
 
-.. autoclass:: sphinxnotes.render.BaseContextDirective
-   :show-inheritance:
-   :members: process_pending_node, queue_pending_node, queue_context, current_context, current_template
-
-.. autoclass:: sphinxnotes.render.BaseDataDefineDirective
-   :show-inheritance:
-   :members: process_pending_node, queue_pending_node, queue_context, current_schema, current_template
-
-.. autoclass:: sphinxnotes.render.StrictDataDefineDirective
-   :show-inheritance:
-   :members: derive
+.. autodecorator:: sphinxnotes.render.filter
 
 Data, Field and Schema
 ======================

docs/conf.py

@@ -122,23 +122,46 @@
 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]
+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)

docs/conf.rst

@@ -0,0 +1,30 @@
+=============
+Configuration
+=============
+
+The extension provides the following configuration:
+
+.. autoconfval:: 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`
+
+   See :ref:`custom-dir` for example.
+

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']