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

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

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/sphinx-notes/cookiecutter",
-  "commit": "62cd96195962da3392cdc34125c95e9144a5f5ca",
+  "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": "62cd96195962da3392cdc34125c95e9144a5f5ca"
+      "_commit": "4c6b17aec1a4b8ddca95c4882c6bed2bc230d595"
     }
   },
   "directory": null

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinxnotes-render
-Version: 1.0b2
+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.0b2 → sphinxnotes_render-1.0b3}/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,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
 
-extensions.append('sphinx.ext.doctest')
+    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.0b2 → sphinxnotes_render-1.0b3}/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,10 +180,10 @@ DSL                 Input     Result
 ``int, sep by ':'`` ``1:2:3`` :py:`[1, 2, 3]`
 =================== ========= ================
 
-Extending the DSL
+Extending the FDL
 =================
 
-You can extend the DSL by registering custom types, flags, and by-options
+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`.
 
@@ -212,7 +213,7 @@ Adding Custom Flags
 -------------------
 
 Use :meth:`~sphinxnotes.render.data.Registry.add_flag` method of
-:data:`sphinxnotes.render.REGISTRY` to add a new type:
+:data:`sphinxnotes.render.REGISTRY` to add a new flag:
 
 >>> from sphinxnotes.render import REGISTRY
 >>> REGISTRY.data.add_flag('unique', default=False)

{sphinxnotes_render-1.0b2 → 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:`dsl` and :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,10 @@ Contents
 
 .. toctree::
    :caption: Contents
+   :maxdepth: 2
 
+   usage
+   tmpl
    dsl
    api
    changelog