sphinxcontrib.datatemplates — Render Your Data Readable¶
sphinxcontrib.datatemplates helps you use static data in machine
readable format in your documentation by letting you define Jinja2
templates to turn JSON, YAML, XML, or CSV data into reStructuredText
for Sphinx to render as part of its output.
- Repo: https://github.com/sphinxcontrib/sphinxcontrib.datatemplates
- Docs: http://sphinxcontribdatatemplates.readthedocs.io/
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.
csvheaderoptional flag, CSV only- Set to use
csv.DictReaderfor reading the file. If not setcsv.reader()is used. csvdialectoptional, CSV only, eitherautoor one fromcsv.list_dialects()- Set to select a specific
csv.Dialect. Set toauto, 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.
JSON Samples¶
Data File¶
{
"key1": "value1",
"key2": [
"list item 1",
"list item 2",
"list item 3"
],
"nested-list": [
["a", "b", "c"],
["A", "B", "C"]
],
"mapping-series": [
{"cola": "a", "colb": "b", "colc": "c"},
{"cola": "A", "colb": "B", "colc": "C"}
]
}
Template File¶
.. -*- mode: rst -*-
Static Heading
--------------
Individual Item
~~~~~~~~~~~~~~~
{{ data['key1'] }}
List of Items
~~~~~~~~~~~~~
{% for item in data['key2'] %}
- {{item}}
{% endfor %}
Nested List Table
~~~~~~~~~~~~~~~~~
Rendering a table from a list of nested sequences using hard-coded
headers.
{{ make_list_table(
['One', 'Two', 'Three'],
data['nested-list'],
title='Table from nested lists',
) }}
Mapping Series Table
~~~~~~~~~~~~~~~~~~~~
Rendering a table from a list of nested dictionaries using dynamic
headers.
{{ make_list_table_from_mappings(
[('One', 'cola'), ('Two', 'colb'), ('Three', 'colc')],
data['mapping-series'],
title='Table from series of mappings',
) }}
YAML Samples¶
Data File¶
---
key1: value1
key2:
- list item 1
- list item 2
- list item 3
nested-list:
- ['a', 'b', 'c']
- ['A', 'B', 'C']
mapping-series:
- cola: a
colb: b
colc: c
- cola: A
colb: B
colc: C
Template File¶
.. -*- mode: rst -*-
Static Heading
--------------
Individual Item
~~~~~~~~~~~~~~~
{{ data['key1'] }}
List of Items
~~~~~~~~~~~~~
{% for item in data['key2'] %}
- {{item}}
{% endfor %}
Nested List Table
~~~~~~~~~~~~~~~~~
Rendering a table from a list of nested sequences using hard-coded
headers.
{{ make_list_table(
['One', 'Two', 'Three'],
data['nested-list'],
title='Table from nested lists',
) }}
Mapping Series Table
~~~~~~~~~~~~~~~~~~~~
Rendering a table from a list of nested dictionaries using dynamic
headers.
{{ make_list_table_from_mappings(
[('One', 'cola'), ('Two', 'colb'), ('Three', 'colc')],
data['mapping-series'],
title='Table from series of mappings',
) }}
CSV Samples¶
Data File¶
a b c
Eins Zwei Drei
1 2 3
I II III
Template File¶
.. -*- mode: rst -*-
Static Heading
--------------
Individual Cell in Row
~~~~~~~~~~~~~~~~~~~~~~
{{ data[0].a }}
List of Cells in Row
~~~~~~~~~~~~~~~~~~~~
{% for item in data[0].items() %}
- {{item[0]}}: {{item[1]}}
{% endfor %}
Mapping Series Table
~~~~~~~~~~~~~~~~~~~~
Rendering a table from a list of nested dictionaries using dynamic
headers.
{{ make_list_table_from_mappings(
[('One', 'a'), ('Two', 'b'), ('Three', 'c')],
data,
title='Table from series of mappings',
) }}
Code¶
.. datatemplate::
:source: sample.csv
:template: csv-sample.tmpl
:csvheaders:
:csvdialect: excel-tab
XML Samples¶
Data File¶
<sample>
<key1>value1</key1>
<key2>
<item>list item 1</item>
<item>list item 2</item>
<item special='yes'>list item 3</item>
</key2>
<mappingseries>
<mapping>
<cola special='yes'>a</cola>
<colb>b</colb>
<colc>c</colc>
</mapping>
<mapping>
<cola>A</cola>
<colb special='yes'>B</colb>
<colc>C</colc>
</mapping>
</mappingseries>
</sample>
Template File¶
.. -*- mode: rst -*-
Static Heading
--------------
Individual Item
~~~~~~~~~~~~~~~
{{ data.find('key1').text }}
List of Items
~~~~~~~~~~~~~
{% for item in data.find('key2') %}
- {{item.text}}
{% endfor %}
XPath for Items
~~~~~~~~~~~~~~~
See `XPath support <https://docs.python.org/3/library/xml.etree.elementtree.html#xpath-support>`_
{% for item in data.findall(".//*[@special='yes']") %}
- {{item.text}}
{% endfor %}