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) viacsv.reader()
orcsv.DictReader
depending onheader
and render usingtemplate
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 setcsv.reader()
is used.
- :dialect: optional¶
Set to select a specific
csv.Dialect
. Set toauto
, 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) viadbm.open()
and render usingtemplate
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 inconf.py
) viaimportlib.import_module()
and render usingtemplate
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) viajson.load()
and render usingtemplate
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
asdata
and render usingtemplate
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) viaxml.etree.ElementTree.parse()
(actually usingdefusedxml
) and render usingtemplate
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 usingtemplate
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
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.