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

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

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/sphinx-notes/cookiecutter",
-  "commit": "634c4022e575bd086ea47f3b42feafe24e14a939",
+  "commit": "4c6b17aec1a4b8ddca95c4882c6bed2bc230d595",
   "checkout": null,
   "context": {
     "cookiecutter": {
@@ -20,7 +20,7 @@
       "sphinx_version": "7.0",
       "development_status": "3 - Alpha",
       "_template": "https://github.com/sphinx-notes/cookiecutter",
-      "_commit": "634c4022e575bd086ea47f3b42feafe24e14a939"
+      "_commit": "4c6b17aec1a4b8ddca95c4882c6bed2bc230d595"
     }
   },
   "directory": null

sphinxnotes_render-1.0b3/.github/workflows/test.yml

@@ -0,0 +1,25 @@
+name: Test
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: '0 7 * * 6'
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v5
+      with:
+        python-version-file: 'pyproject.toml'
+    - run: python3 -m pip install .[test]
+    - run: make test
+  doctest:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v5
+      with:
+        python-version-file: 'pyproject.toml'
+    - run: python3 -m pip install .[docs]
+    - run: make doctest

{sphinxnotes_render-1.0b1 → sphinxnotes_render-1.0b3}/Makefile

@@ -27,7 +27,11 @@ fmt:
 
 .PHONY: test
 test:
-	$(PY) -m unittest discover -s tests -v
+	$(PY) -m pytest tests/ -v
+
+.PHONY: doctest
+doctest:
+	$(MAKE) doctest -C docs/
 
 ################################################################################
 # Distribution Package

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinxnotes-render
-Version: 1.0b1
+Version: 1.0b3
 Summary: A framework to define, constrain, and render data in Sphinx documentation
 Author: Shengyu Zhang
 Maintainer: Shengyu Zhang
@@ -42,6 +42,7 @@ 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"
 Dynamic: license-file
 
 .. This file is generated from sphinx-notes/cookiecutter.

sphinxnotes_render-1.0b3/docs/api.rst

@@ -0,0 +1,164 @@
+==============
+API References
+==============
+
+The Render Pipeline
+===================
+
+The pipeline defines how nodes carrying data are generated and when they are
+rendered as part of the document.
+
+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:
+
+   - :ref:`context`, the dynamic content of a Jinja template
+
+   - :py:class:`~sphinxnotes.render.Template`,
+      the Jinja template for rendering context to markup text
+      (reStructuredText or Markdown)
+
+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`.
+
+For a task-oriented explanation of template variables, extra context, and phase
+selection, see :doc:`tmpl`.
+
+Node
+-----
+
+.. autoclass:: sphinxnotes.render.pending_node
+
+.. _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.
+
+.. autoclass:: sphinxnotes.render.GlobalExtraContxt
+
+.. autoclass:: sphinxnotes.render.ParsePhaseExtraContext
+
+.. autoclass:: sphinxnotes.render.ResolvePhaseExtraContext
+
+.. autoclass:: sphinxnotes.render.ExtraContextRegistry
+   :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
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. 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
+
+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
+   .. autoproperty:: extra_context

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

@@ -23,6 +23,8 @@ version = release = '1.0a0'
 # ones.
 extensions = [
     'sphinx.ext.githubpages',
+    'sphinx.ext.doctest',
+    'sphinx.ext.viewcode',
     'sphinx_design',
     'sphinx_copybutton',
     'sphinx_last_updated_by_git',
@@ -117,10 +119,26 @@ 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')
+
+extensions.append('sphinxnotes.data')
 
 # CUSTOM CONFIGURATION
 
-_ = extensions.pop() # no need to load extension
-primary_domain = 'py'
+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')
+
+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)

sphinxnotes_render-1.0b3/docs/dsl.rst

@@ -0,0 +1,240 @@
+==========================
+Field Description Language
+==========================
+
+.. default-domain:: py
+.. highlight:: python
+.. role:: py(code)
+   :language: Python
+
+
+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
+======
+
+.. productionlist::
+   dsl          : modifier ("," modifier)*
+   modifier     : type_modifier | form_modifier | flag | by_option
+
+.. glossary::
+
+   Modifier
+      There are four categories of modifiers:
+
+   Type modifier
+      Specifies the element type (scalar value)
+
+   Form modifier
+      Specifies a container type with element type
+
+   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]
+
+
+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 it looks like a Python literal (e.g., ``"hello"``), it is parsed accordingly.
+
+Examples:
+
+======= ========= =============
+DSL     Input     Result
+------- --------- -------------
+``int`` ``42``    :py:`42`
+``str`` ``hello`` :py:`"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:
+
+================ =========== =====================
+DSL              Input       Result
+---------------- ----------- ---------------------
+``list of int``  ``1, 2, 3`` :py:`[1, 2, 3]`
+``lines of str`` ``a\nb``    :py:`['a', 'b']`
+``words of str`` ``a b c``   :py:`['a', 'b', 'c']`
+================ =========== =====================
+
+Flag
+====
+
+A flag is a boolean modifier that can be either on or off.
+
+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::
+   :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>``.
+
+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:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Modifier
+     - Type
+     - Description
+   * - ``sep by '<sep>'``
+     - :py:class:`str`
+     - Custom separator for value form. Implies ``list`` if no form specified.
+
+Examples:
+
+=================== ========= ================
+DSL                 Input     Result
+------------------- --------- ----------------
+``str, sep by '|'`` ``a|b``   :py:`['a', 'b']`
+``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.0b1 → sphinxnotes_render-1.0b3}/docs/index.rst

@@ -30,11 +30,6 @@ Introduction
 
 A framework to define, constrain, and render data in Sphinx documentation.
 
-.. seealso:: `sphinxnotes-any`__ and `sphinxnotes-data`__ 
-
-   __ https://sphinx.silverrainz.me/any/
-   __ https://sphinx.silverrainz.me/data/
-
 .. INTRODUCTION END
 
 Getting Started
@@ -42,8 +37,18 @@ Getting Started
 
 .. ADDITIONAL CONTENT START
 
-This extension is not intended to be used directly by Sphinx user.
-It is for Sphinx extension developer, please refer to :doc:`api`.
+.. note::
+
+   This extension is **aimed at advanced Sphinx users or extension developers**.
+
+   If you are new to Sphinx, you may instersting with
+   :parsed_literal:`sphinxnotes.data__` or :parsed_literal:`sphinxnotes.any__`.
+
+   __ https://sphinx.silverrainz.me/data
+   __ https://sphinx.silverrainz.me/any
+
+We cannot get you started with this short section; please refer to the
+:doc:`usage` for more detailed information.
 
 .. ADDITIONAL CONTENT END
 
@@ -52,7 +57,11 @@ Contents
 
 .. toctree::
    :caption: Contents
+   :maxdepth: 2
 
+   usage
+   tmpl
+   dsl
    api
    changelog