Using datatemplate

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

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

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

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

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

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

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

When a datatemplate directive is processed, the data 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.

Template Helpers

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

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.