# Using datatemplate

The `datatemplate` directive is the interface between the data source and the rendering template.

## Directives

.. datatemplate:csv:: source-path

  Load file at `source-path` (relative to the documentation build directory) via `csv.reader()` or `csv.DictReader` depending on `header` and render using `template` given in directive body.

  :template: template name, optional

    The name of a template file on the Sphinx template search path. Overrides directive body.

  :encoding: optional, defaults to ``utf-8-sig``

    The text encoding that will be used to read the source file. See `standard-encodings`

  :header: flag, optional

    Set to use `csv.DictReader` for reading the file. If not set `csv.reader()` is used.

  :dialect: optional

    Set to select a specific `csv.Dialect`. Set to `auto`, to try autodetection. If not set the default dialect is used.

.. datatemplate:dbm:: source-path::

  Load DB at `source-path` (relative to the documentation build directory) via `dbm.open()` and render using `template` given in directive body.

  :template: template name, optional

    The name of a template file on the Sphinx template search path. Overrides directive body.

.. datatemplate:import-module:: module-name

  Load module `module-name` (must be importable in `conf.py`) via `importlib.import_module()` and render using `template` given in directive body.

  :template: template name, optional

    The name of a template file on the Sphinx template search path. Overrides directive body.

.. datatemplate:json:: source-path

  Load file at `source-path` (relative to the documentation build directory) via `json.load()` and render using `template` given in directive body.

  :template: template name, optional

    The name of a template file on the Sphinx template search path. Overrides directive body.

  :encoding: optional, defaults to ``utf-8-sig``

    The text encoding that will be used to read the source file. See `standard-encodings`

.. datatemplate:nodata::

  Load `None` as `data` and render using `template` given in directive body.

  :template: template name, optional

    The name of a template file on the Sphinx template search path. Overrides directive body.

.. datatemplate:xml:: source-path

  Load file at `source-path` (relative to the documentation build directory) via `xml.etree.ElementTree.parse()` (actually using `defusedxml`) and render using `template` given in directive body.

  :template: template name, optional

    The name of a template file on the Sphinx template search path. Overrides directive body.

.. datatemplate:yaml:: source-path

  Load file at `source-path` (relative to the documentation build directory) via PyYAML (`yaml.safe_load()`) and render using `template` given in directive body.

  :template: template name, optional

    The name of a template file on the Sphinx template search path. Overrides directive body.

  :encoding: optional, defaults to ``utf-8-sig``

    The text encoding that will be used to read the source file. See `standard-encodings`

  :multiple-documents: flag, optional

    Set to read multiple documents from the file into a `list`

## Template Files

The `datatemplate` directive uses Sphinx’s templates_path configuration setting to search for template files.

## Template Context

When a `datatemplate` directive is processed, the data from the `source` is passed to the template through its context so that the symbol `data` is available as a global variable.

Important

The data is loaded from the source and passed directly to the template. No pre-processing is done on the data, so the template needs to handle aspects like `None` values and fields that have values that may interfere with parsing reStructuredText.

The application configuration for a project will be passed to the template as the symbol `config`. This can be used, for example, to access HTML context via `config.html_context`. Refer to the Inline Sample for an example.

The Sphinx build environment for a project will be passed to the template as the symbol `env`. This can be used to access all of the information that Sphinx has about the current build, including settings, and document names. Refer to the No Data Sample for an example.

## Template Helpers

These helper functions are exposed using their short name (without the module prefix) in the template context.

sphinxcontrib.datatemplates.helpers.escape_rst(s)

  Escape string for inclusion in RST documents.

  See https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#escaping-mechanism

  Parameters:

    s – String for escaping

sphinxcontrib.datatemplates.helpers.escape_rst_url(s)

  Escape string for inclusion in URLs in RST documents.

  See https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#escaping-mechanism

  Parameters:

    s – String for escaping

sphinxcontrib.datatemplates.helpers.make_list_table(headers, data, title='', columns=None)

  Build a list-table directive.

  Parameters:

    - headers – List of header values.

    - data – Iterable of row data, yielding lists or tuples with rows.

    - title – Optional text to show as the table title.

    - columns – Optional widths for the columns.

sphinxcontrib.datatemplates.helpers.make_list_table_from_mappings(headers, data, title, columns=None)

  Build a list-table directive.

  Parameters:

    - headers – List of tuples containing header title and key value.

    - data – Iterable of row data, yielding mappings with rows.

    - title – Optional text to show as the table title.

    - columns – Optional widths for the columns.