Usage¶

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

Directives¶

.. data.define:: name¶

Define data and render it inplace.

:*: (depends on the schema)¶: This directive uses the “freestyle” option spec, if no any data.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 Main Context, which looks like:

Source

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

   I like fish!

Result

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

   # Lifted attrs
   'color': 'black and brown',
}

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

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

.. data.template::¶

Define a template for rendering data. The template will be applied to the subsequent data.define directives. Refer to Templating for guide of writing template.

:on: (choice)¶: Determinate Render Phases of template. Defaults to parsing. Available values: ['parsing', 'parsed', 'resolving'].

:debug: (flag)¶: Enable debug report for template rendering.

:extra: (space separted list)¶: List of Extra Context to be used in the template.

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

Example:

Source

.. data.template::

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

   {{ content }}.

.. data.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!.

.. data.schema:: <DSL>¶

Define a schema for restricting data. The schema will be applied to the subsequent data.define directives. We use a custom Domain Specified Language (DSL) to descript field’s type, please refer to Field Description Language.

:*: (<DSL>)¶

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

content: <DSL>

Source

.. data.schema:: int

.. data.template::

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

.. data.define:: 1

Result

1 + 1 = 2

.. data.render::¶

Render a template immediately without defining data. This is useful when you want to render some fixed content or predefined data.

:on:¶

:debug:¶

:extra:¶: The options of this directive are same to data.template.

Source

.. data.render::

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

Result

1 + 1 = 2

Defining Custom Directives¶

Instead of using data.define, data.template, and data.schema directives to define data in documents, you can define custom directives in conf.py using the render_ext_data_define_directives configuration option.

This is useful when you want to create a reusable directive with a fixed schema and template across multiple documents.

First, add 'sphinxnotes.render.ext' to your extension list like what we do in Getting Started.

Then add the following code to your conf.py:

render_ext_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 }}.',
           ]),
       },
   },
}

This creates a .. cat:: directive that requires a name argument and accepts a color options and a content. Use it in your document:

Source

.. cat:: 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!.

For more details please refer to the render_ext_data_define_directives configuration value.