update

Author: SilverRainZ

docs/app/tmpl.rst

@@ -1,6 +1,6 @@
-==========
-Templating
-==========
+=================
+Guide: Templating
+=================
 
 This guide explains how to write Jinja2 templates for the ``sphinxnotes.render``
 -based extension (``sphinxnotes.render.ext``, ``sphinxnotes.any`` and etc.).
@@ -145,6 +145,8 @@ extension defines the schema through the :rst:dir:`data.schema` directive or
    :py:class:`~sphinxnotes.render.BaseDataDefineDirective` or
    :py:class:`~sphinxnotes.render.BaseDataDefineRole` can generate main context.
 
+.. _extra-context:
+
 Extra Context
 -------------
 
@@ -158,7 +160,7 @@ so you need to declare them in advance, and load it in the template using the
 ``load_extra()`` function:
 
 The way of declaring extra context is vary depending on the extension you use.
-For ``sphinxnotes.render.ext``, :rst:dir:`data.template.extra`,
+For ``sphinxnotes.render.ext`` extension, :rst:dir:`data.template.extra`,
 :rst:dir:`data.render.extra` and the ``templat.extra`` field of
 :confval:`data_define_directives` are for this.
 
@@ -170,7 +172,7 @@ For ``sphinxnotes.render.ext``, :rst:dir:`data.template.extra`,
 
       {% set doc = load_extra('doc') %}
 
-      Document Title: {{ doc.title }}
+      Document Title: "{{ doc.title }}"
 
 Built-in Extra Contexts
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -190,8 +192,8 @@ The following extra contexts are available:
 
          {% set app = load_extra('sphinx') %}
 
-         We have {{ app.extensions | length }}
-         extensions loaded.
+         **{{ app.extensions | length }}**
+         extensions are loaded.
 
 ``env``
    :Phase: all
@@ -206,8 +208,8 @@ The following extra contexts are available:
 
          {% set env = load_extra('env') %}
 
-         We have {{ env.all_docs | length }}
-         documents.
+         **{{ env.all_docs | length }}**
+         documents found.
 
 ``markup``
    :Phase: parsing and later
@@ -221,11 +223,14 @@ The following extra contexts are available:
       .. data.render::
          :extra: markup
 
-         {% set markup = load_extra('markup') | jsonify %}
+         {%
+         set m = load_extra('markup')
+                 | jsonify
+         %}
 
          .. code::
 
-            {% for line in markup.split('\n') -%}
+            {% for line in m.split('\n') -%}
             {{ line }}
             {% endfor %}
  
@@ -241,8 +246,8 @@ The following extra contexts are available:
       .. data.render::
          :extra: section
 
-         Title of current section is
-         {{ load_extra('section').title }}
+         Seciont Title:
+         "{{ load_extra('section').title }}"
 
 ``doc``
    :Phase: parsing and later
@@ -255,15 +260,20 @@ The following extra contexts are available:
       .. data.render::
          :extra: doc
 
-         Title of current document is
+         Document titie:
          "{{ load_extra('doc').title }}".
 
 .. seealso:: :ref:`extending-extra-context`
 
 TODO: the proxy object.
 
 Built-in Filters
-----------------
+================
+
+In addition to the `Builtin Jinia Filters`__, this extension also provides the
+following filters:
+
+__ https://jinja.palletsprojects.com/en/stable/templates/#builtin-filters
 
 ``roles``
    Produces role markup from a sequence of strings.
@@ -282,8 +292,25 @@ Built-in Filters
          :Text: ``{{ text }}``
          :Rendered: {{ text }}
 
+``jsonify``
+   Convert value to JSON.
+
+   .. example::
+      :style: grid
+
+      .. data.render::
+
+         {% set text = {'name': 'mimi'} %}
+
+         :Strify: ``{{ text }}``
+         :JSONify: ``{{ text | jsonify }}``
+
+.. seealso:: :ref:`ext-filters`
+
+.. _render-phases:
+
 Render Phases
--------------
+=============
 
 Each template has a render phase that determines when it is processed:
 
@@ -365,20 +392,30 @@ Each template has a render phase that determines when it is processed:
    Internally, each phase corresponds to a :py:class:`~sphinxnotes.render.Phase`
    enum value. The ``on`` option maps to :py:attr:`~sphinxnotes.render.Template.phase`.
 
+.. _debug:
+
 Debugging
----------
+=========
 
 Enable the debug option to see a detailed report when troubleshooting templates:
 
-.. code-block:: rst
+.. example::
+   :style: grid
 
    .. data.render::
       :debug:
 
-      {{ name }}
-
-The debug report includes: resolved context, available extra-context keys,
-template source, rendered markup text, and the final nodes produced.
+      {{ 1 + 1 }}
 
 This is especially useful when a template fails due to an undefined variable,
 unexpected data shape, or invalid generated markup.
+
+Jinja Template Technical Details
+================================
+
+Templates are rendered in a sandboxed Jinja2 environment.
+
+- Undefined variables raise errors by default (``undefined=DebugUndefined``)
+- Extension ``jinja2.ext.loopcontrols``, ``jinja2.ext.do`` are enabled by default.
+- Output is plain markup text, so you can generate lists, directives, roles,
+  and other reStructuredText constructs.

docs/app/usage.rst

@@ -48,16 +48,18 @@ Directives
    .. rst:directive:option:: on
       :type: choice
 
-      Determinate when the template is rendered. Defaults to ``parsing``.
-
+      Determinate :ref:`render-phases` of template. Defaults to ``parsing``.
       Available values: ``['parsing', 'parsed', 'resolving']``.
 
-      See :external+render:ref:`phases` for more details.
-
    .. rst:directive:option:: debug
       :type: flag
 
-      Enable debug report for template rendering.
+      Enable :ref:`debug report <debug>` for template rendering.
+
+   .. rst:directive:option:: extra
+      :type: space separted list
+
+      List of :ref:`extra-context` to be used in the template.
 
    The content of the directive should be Jinja2 Template, please refer to
    ::doc:`/fw/templating`.
@@ -112,15 +114,18 @@ Directives
    Render a template immediately without defining data.
    This is useful when you want to render some fixed content or predefined data.
 
-   The options of this directive are same to :rst:dir`data.template`.
+   .. rst:directive:option:: on
+   .. rst:directive:option:: debug
+   .. rst:directive:option:: extra
+
+      The options of this directive are same to :rst:dir:`data.template`.
 
    .. example::
       :style: grid
 
       .. data.render::
 
-         Sphinx has **{{ _sphinx.extensions | length }}** extensions loaded.
-
+         ``1 + 1 = {{ 1 + 1 }}``
 
 .. _ext-usage-custom-directive:
 

docs/fw/ext.rst

@@ -2,22 +2,20 @@
 Guide: Extending
 ================
 
-.. _extending-extra-context:
-
 Extending the FDL
 =================
 
 You can extend the :doc:`dsl` by registering custom types, flags, and by-options
-through the :attr:`~sphinxnotes.render.Registry.data` attribute of
-:data:`sphinxnotes.render.REGISTRY`.
+through the :py:attr:`~sphinxnotes.render.Registry.data` attribute of
+:py: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:
+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
 >>> 
@@ -36,8 +34,8 @@ Use :meth:`~sphinxnotes.render.data.REGISTRY.add_type` method of
 Adding Custom Flags
 -------------------
 
-Use :meth:`~sphinxnotes.render.data.Registry.add_flag` method of
-:data:`sphinxnotes.render.REGISTRY` to add a new flag:
+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
 >>> REGISTRY.data.add_flag('unique', default=False)
@@ -50,8 +48,8 @@ True
 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:
+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
 >>> REGISTRY.data.add_by_option('group', str)
@@ -63,7 +61,7 @@ Use :meth:`~sphinxnotes.render.data.Registry.add_by_option` method of
 >>> field.index
 ['month', 'year']
 
-.. _ext-extra-contexts:
+.. _ext-extra-context:
 
 Extending Extra Contexts
 ========================
@@ -77,10 +75,14 @@ The decorated class must be one of the following classes:
 :py:class:`~sphinxnotes.render.ResolvingPhaseExtraContext`,
 :py:class:`~sphinxnotes.render.GlobalExtraContext`.
 
+TODO
+
 .. _ext-filters:
 
 Extending Filters
 =================
 
 Template filters are registered by a
 :py:deco:`sphinxnotes.render.filter` function decorator.
+
+TODO

docs/fw/tmpl.rst

@@ -11,13 +11,6 @@ be comfortable with basic Jinja2_ syntax before reading this page.
 Jinja Environment
 =================
 
-Templates are rendered in a sandboxed Jinja2 environment.
-
-- Undefined variables raise errors by default (``undefined=DebugUndefined``)
-- Extension ``jinja2.ext.loopcontrols``, ``jinja2.ext.do`` are enabled by default.
-- Output is plain markup text, so you can generate lists, directives, roles,
-  and other reStructuredText constructs.
-
 Built-in filters
 ----------------