Using datatemplate¶

The datatemplate directive is the interface between the data source and the rendering template. It requires two parameters.

.. datatemplate::¶

source: The source file, relative to the documentation build directory.
template: The name of a template file on the Sphinx template search path.
csvheader optional flag, CSV only: Set to use csv.DictReader for reading the file. If not set csv.reader() is used.
csvdialect optional, CSV only, either auto or one from csv.list_dialects(): Set to select a specific csv.Dialect. Set to auto, to try autodetection. If not set the default dialect is used.

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.

Format	`data` type
JSON	the object returned by `json.safe_load()` (varies based on input)
YAML	the object returned by the PyYAML function `yaml.safe_load()` (varies based on input)
XML	`xml.etree.ElementTree.ElementTree`
CSV	`list` of `tuple` or `dict` (when `csvheaders` option is specified)

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.