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 Directive and Role Context. A data context looks like this:

Source

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

:on: (choice)¶

Determinate when the template is rendered. Defaults to parsing.

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

See Render Phases for more details.

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

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 applid to the subsequent data.define directives.

:*: (<DSL>)¶

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

content: <DSL>

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

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.

The options of this directive are same to :rst:dir`data.template`.

Source

.. data.render::

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

Result

Sphinx has 73 extensions loaded.

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 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.data' to your extension list like what we do in Getting Started.

Then add the following code to your conf.py:

data_define_directives = {
   'cat': {
       'schema': {
           'name': 'str, required',
           'attrs': {
               'color': 'str',
           },
           'content': 'str, required'
       },
       'template': {
           'debug': False,
           'on': 'parsing',
           '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 data_define_directives configuration value.