Usage

This extension provides directives and roles for user to define, validate, and render data.

Directives

.. define:: name

Define data and render it inplace.

:*: (depends on the schema)

This directive uses the “freestyle” option spec, if no any schema applied, it allows arbitrary options to be specified. Otherwise, the option name and value is depends on the schema.

The directive generates a dict-like data structure, we call it data-context. A data context looks like this:

Source
.. define:: mimi
   :color: black and brown

   I like fish!
Result
{
   'name': 'mimi',
   'attrs': {'color': 'black and brown'},
   'content': 'I like fish!'

   # Attributes are copied and
   # lifted to the top level for convenience.
   'color': 'black and brown',

}

The fields of data context can be restricted and customized, see schema for details.

The data will be rendered by template defined by the previous template directive.

.. template::

Define a template for rendering data. The template will be applied to the subsequent define directives.

:on: (choice)

Determinate when the template is rendered. Defaults to parsing.

Available values: ['parsing', 'parsed', 'resolving'].

See phases for more details.

:debug: (flag)

Enable debug report for template rendering.

The content of the directive should be Jinja2 Template, please refer to tmpl.

Example:

Source
.. template::

   Hi human! I am a cat named {{ name }}, I have {{ color }} fur.

   {{ content }}.

.. define:: mimi
   :color: black and brown

   I like fish!
Result

Hi human! I am a cat named mimi, I have black and brown fur.

I like fish!.

.. schema:: <DSL>

Define a schema for restricting data. The schema will be applid to the subsequent define directives.

:*: (<DSL>)

This directive uses the “freestyle” option spec, which allows arbitrary options to be specified. Each option corrsponding to an option of define directive.

content: <DSL>

We use a custom Domain Specified Language (DSL) to descript field’s type, please refer to Field Declaration DSL.

Source
.. schema:: int

.. template::

   ``{{ name }} + 1 =  {{ name + 1 }}``

.. define:: wow

.. define:: 1
Result

1 + 1 =  2

.. render::

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`template`.

Source
.. render::

   Sphinx has **{{ _sphinx.extensions | length }}** extensions loaded.
Result

Sphinx has 73 extensions loaded.